vite-plugin-i18n-translations

(This file is generated by GPT4-o)

A Vite plugin package that provides two utilities for managing internationalization (i18n) translation files in your project:

• extractTranslations: Consolidates scattered component-level translation files by namespace into merged translation files during the build process.
• copyTranslations: Copies consolidated translation files from node_modules directories to the application’s public folder for use at runtime.
• localeHotReload: Enables hot reloading for localization files in your development environment. When changes are made to .i18n.json files, the plugin triggers a custom locales-update event via Vite’s WebSocket server, allowing your application to dynamically refresh localized content without requiring a full page reload.

Installation

Install the package using npm or yarn:

npm install vite-plugin-i18n-translations --save-dev

Usage

Import the plugins into your Vite configuration file (vite.config.js or vite.config.ts) and include them in the plugins array.

// vite.config.js
import { defineConfig } from 'vite';
import { extractTranslations, copyTranslations } from 'vite-plugin-i18n-translations';

export default defineConfig({
  plugins: [
    extractTranslations({
      ns: {
        // Namespace configurations
      },
    }),
    copyTranslations({
      from: [
        // Source directories
      ],
    }),
    localesHotReload(),
  ],
});

extractTranslations

The extractTranslations plugin is designed to be used in component libraries. It consolidates scattered component-level translation files by namespace into merged translation files during the build process.

Configuration

The plugin accepts a configuration object with the following properties:

• ns (required): An object mapping namespace names to their respective source paths.
• output (optional): The output directory relative to the build output directory (default is 'locales', i.e., ./dist/locales).

extractTranslations({
  ns: {
    // Namespace configurations (required)
  },
  output: 'locales', // Output directory (optional)
});

Example

// vite.config.js
import { defineConfig } from 'vite';
import { extractTranslations } from 'vite-plugin-i18n-translations';

export default defineConfig({
  plugins: [
    extractTranslations({
      ns: {
        editor: './src/editor',
        player: './src/player',
      },
      output: 'locales', // Optional: defaults to 'locales'
    }),
  ],
});

Translation Files Structure

Translation files should follow these naming conventions:

<key-prefix>."["<lang>"]".i18n.json

• key-prefix: A string representing the prefix for translation keys, such as 'commands' or 'commands.inline'.
• lang: Language code, e.g., 'en', 'zh', 'en-US'.

Examples:

• commands.[en].i18n.json
• commands.inline.[zh].i18n.json

Place these files under the paths specified in the ns configuration.

Plugin Behavior

• Key Prefixing: All keys in the original translation files will be prefixed with the . This helps in organizing translations and avoiding key collisions.
• Merging Translations: The plugin merges all translation entries into a single JSON file per namespace and language.
• Output Files: The merged translation files are generated into the specified output folder within the build output directory (e.g., ./dist/locales).

Example Input Files:

• ./src/editor/translations/commands.[en].i18n.json:

{
  "save": "Save",
  "open": "Open"
}

• ./src/editor/translations/commands.[zh].i18n.json:

{
  "save": "保存",
  "open": "打开"
}

Example Output Files:

After building, the plugin generates:

• ./dist/locales/en/editor.json:

{
  "commands.save": "Save",
  "commands.open": "Open"
}

• ./dist/locales/zh/editor.json:

{
  "commands.save": "保存",
  "commands.open": "打开"
}

copyTranslations

The copyTranslations plugin is intended for applications that use the component library. It copies the consolidated translation files from the node_modules directory to the application’s public folder, making them available at runtime.

Configuration

The plugin accepts a configuration object with the following properties:

• from (required): An array of source directories from which to copy translation files. Typically, these are paths to node_modules directories of component libraries.
• to (optional): The target directory relative to the project root where the translation files should be copied (default is 'public').

copyTranslations({
  from: [
    // Source directories (required)
  ],
  to: 'public', // Target directory (optional)
});

Example

// vite.config.js
import { defineConfig } from 'vite';
import { copyTranslations } from 'vite-plugin-i18n-translations';

export default defineConfig({
  plugins: [
    copyTranslations({
      from: ['./node_modules/@grafton/xgent/dist'],
      to: 'public/locales', // Optional: defaults to 'public'
    }),
  ],
});

Plugin Behavior

• File Copying: Recursively copies all JSON files from the specified source directories’ locales/ folders to the target directory, preserving the directory structure.
• Availability at Runtime: Ensures that the translation files are available in the public directory at runtime, typically served as static assets.

Example Input Files in node_modules:

• ./node_modules/@xgent/grafton/dist/locales/en/editor.json
• ./node_modules/@xgent/grafton/dist/locales/zh/editor.json

Example Output Files in public:

After running the plugin, the files are copied to:

• ./public/locales/en/editor.json
• ./public/locales/zh/editor.json

copyTranslations({
  from: [
    './node_modules/@xgent/grafton/dist',
    './node_modules/another-library/dist',
  ],
});

License

This package is licensed under the MIT License.