@bgscore/react-i18n 🚀

Vite plugin to automatically generate TypeScript-safe i18n namespaces and translation keys from JSON files in React projects.

Main Features

• 🌐 Auto-detects i18n JSON files in your project
• 🔧 Generates I18nNamespaceMap interface automatically
• ⚡ Fully TypeScript-safe translation keys
• 🔄 Supports nested JSON objects (a.b.c) flattened for keys
• 💡 HMR support during development

Installation

npm install @bgscore/react-i18n
# or
pnpm add @bgscore/react-i18n

Usage

Vite Configuration

Add this plugin to your Vite configuration (vite.config.js or vite.config.ts):

import { defineConfig } from "vite"
import react from "@vitejs/plugin-react-swc"
import reactI18n from "@bgscore/react-i18n/plugin";

export default defineConfig({
    plugins: [
        react(),
        reactI18n({
            i18nDirName: "i18n",
            outputFileName: "i18n.types.ts",
            namespaceInterfaceName: "I18nNamespaceMap"
        }),
    ],
})

Folder Structure

The plugin automatically generates TypeScript types from your JSON files. Example structure:

src/
├── components/
│   ├── home/
│   │   ├── i18n/
│   │   │   ├── id.json
│   │   │   └── en.json
│   │   └── Home.tsx
│   ├── dashboard/
│   │   ├── i18n/
│   │   │   └── id.json
│   │   └── Dashboard.tsx

Generated Output

For each i18n folder, a i18n.types.ts file will be generated containing a I18nNamespaceMap interface:

declare global {
    interface I18nNamespaceMap {
        "components.home": "title" | "desc" | "a.b";
        "components.dashboard": "title" | "subtitle";
    }
}

export {};

Using useTranslation Hook

import useTranslation from "hooks/useTranslation";

export default function Home() {
    const { t, ns } = useTranslation("components.home");

    return (
        <div>
            <h1>{t("title")}</h1>
            <p>{t("desc")}</p>
        </div>
    );
}

The hook provides:

• t(key: string, options?): Type-safe translation function
• ns: Current namespace
• All keys are inferred from the generated I18nNamespaceMap for autocomplete

Example JSON (id.json)

{
  "title": "Beranda",
  "desc": "Selamat datang",
  "a": {
    "b": "Nested key example"
  }
}

This will generate TypeScript keys:

"title" | "desc" | "a.b"

Configuration Options

• i18nDirName: The folder name where i18n JSON files are stored. Default: "i18n".
• outputFileName: Name of the generated TypeScript file. Default: "i18n.types.ts".
• namespaceInterfaceName: Name of the global interface for namespaces. Default: "I18nNamespaceMap".

Development Workflow

• Any changes, addition, or deletion of JSON files in i18n folders will automatically regenerate TypeScript types.
• HMR ensures type updates are available immediately during development.

Contribution

If you want to contribute to this project, please fork the repository and create a pull request.

License

This project is licensed under the MIT License. See the LICENSE file for more information.