vite-plugin-i18n-ally

English | 中文

A vite plugin for lazy loading i18n resources

NOTE: This plugin is independent of the language framework. Whether you use React or Vue (or any other language), as long as it is vite, you can implement lazy loading of internationalization resources based on this plugin

Features

• Seamless development experience, no need to manually import resource files
• Lazy loading language resource files to reduce the size of the first screen resource
• Read the configuration items of i18n-ally by default, no additional configuration is required
• Support vite hmr out of the box

Install

pnpm add vite-plugin-i18n-ally -D

Online Demo

Demo

Plugin Options

If i18n.ally is configured, the plugin will read the configuration by default

Option	Type	Default	Description
localesPaths	string[]	i18n-ally.localesPaths	The directory of language resources, relative to root
root	string	process.cwd()	The project root path
namespace	boolean	i18n-ally.namespace || false	Enable namespace
pathMatcher	string	auto detected by structure	Resource file matching rule
parserPlugins	ParserPlugin[]	Built-in plugins	Resource file parsing plugin
useVscodeI18nAllyConfig	boolean | { stopAt: string }	true	Whether to automatically use i18n-ally configuration, if stopAt is passed in, it will stop detecting in the specified directory

Config Reference

vite.config.ts

import path from 'node:path';
import { defineConfig } from 'vite';
import { i18nAlly } from 'vite-plugin-i18n-ally';

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [i18nAlly()],
});

Client Options

Option	Type	Description
language	string| undefined	The current language
onInited	Function	Callback after initialization
onResourceLoaded	Function	Callback after resource loaded
fallbackLng	string	Fallback language
cache	object	Cache configuration. You can cache the language on html/querystring/cookie/sessionStorage/localStorage

Use with i18next

main.tsx

import i18next from 'i18next';
import React from 'react';
import ReactDOM from 'react-dom/client';
import { initReactI18next } from 'react-i18next';
import { i18nAlly } from 'vite-plugin-i18n-ally/client';
import App from './App';

const root = ReactDOM.createRoot(document.querySelector('#root') as HTMLElement);

const lookupTarget = 'lang';
const fallbackLng = 'en';

i18next.use(initReactI18next).init({
  resources: {}, // !!! important: No resources are added at initialization, otherwise what's lazy loading :)
  nsSeparator: '.',
  keySeparator: '.',
  fallbackLng,
});

const { beforeLanguageChange } = i18nAlly({
  language: i18next.language,
  onInited() {
    root.render(
      <React.StrictMode>
        <App />
      </React.StrictMode>,
    );
  },
  onResourceLoaded: (resource, currentLang) => {
    // Once the resource is loaded, add it to i18next
    Object.keys(resource).forEach((ns) => {
      i18next.addResourceBundle(currentLang, ns, resource[ns]);
    });
  },
  fallbackLng,
  /**
   * Cache configuration
   * You can cache the current language to `html`/`querystring`/`cookie`/`sessionStorage`/`localStorage`
   * If this does not meet your needs, you can use the Detector plugin provided by the i18n library to replace this functionality.
   */
  cache: {
    querystring: lookupTarget, // If you want to cache on querystring
    cookie: 'lang-cookie', // If you want to cache on cookie
  },
});

const i18nextChangeLanguage = i18next.changeLanguage;
i18next.changeLanguage = async (lang: string, ...args) => {
  // Load resources before language change
  await beforeLanguageChange(lang);
  return i18nextChangeLanguage(lang, ...args);
};

Full Example

Please refer to i18next example

vscode i18n-ally configuration reference

.vscode => settings.json

{
  "i18n-ally.localesPaths": ["src/locales"],
  "i18n-ally.keystyle": "nested",
  "i18n-ally.pathMatcher": "{locale}/{namespaces}.{ext}",
  "i18n-ally.namespace": true // If you use `namespace` above, you need to configure
}

⚠️ Warm Tips

Built-in support for json / json5 / yaml / yml / ts / js resource files, customizable plugin parsing language

Thanks

• i18n-ally
• vite

License

MIT