\n\n[](https://embrajs.github.io/i18n)\n[](https://github.com/embrajs/i18n/actions/workflows/build.yml)\n[](https://www.npmjs.com/package/@embra/i18n)\n[](https://embrajs.github.io/i18n/coverage/)\n\nA lightweight, reactive internationalization library.\n\n\n\n## Install\n\n```bash\nnpm add @embra/reactivity @embra/i18n\n```\n\n## Features\n\n- Subscribable reactive `lang$`, `t$` and `locales$`.\n- Lightweight and fast `t()` translation.\n- Nested locale messages.\n- Message formatting and pluralization.\n- Easy dynamic locale loading.\n- Locale namespaces.\n- First-class React support.\n\n## Usage\n\nCreate an I18n instance with static locales:\n\n```ts\nimport { I18n, type Locales } from \"@embra/i18n\";\n\nconst locales: Locales = {\n en: {\n stock: {\n fruit: \"apple\",\n },\n },\n};\n\nconst i18n = new I18n(\"en\", locales);\ni18n.t(\"stock.fruit\"); // apple\n\n// add more locales later\nconst zhCN = await import(`./locales/zh-CN.json`);\ni18n.addLocale(\"zh-CN\", zhCN);\n\n// or replace all locales manually\nconst zhTW = await import(`./locales/zh-TW.json`);\ni18n.locales$.set({ \"zh-TW\": zhTW });\n```\n\nYou can also create an `I18n` instance with preloaded dynamic locales:\n\n```ts\nimport { I18n } from \"@embra/i18n\";\n\nconst i18n = await I18n.preload(\"en\", lang => import(`./locales/${lang}.json`));\n// Locale `./locales/en.json` is preloaded\n\nawait i18n.switchLang(\"zh-CN\"); // Locale `./locales/zh-CN.json` is loaded\n```\n\n### Detect Language\n\nYou can detect language of browser/nodejs via `detectLang`. [BCP 47 tags and sub-tags](https://www.rfc-editor.org/rfc/rfc4647.html#section-3.4) are supported.\n\n```ts\nimport { detectLang } from \"@embra/i18n\";\n\ndetectLang(); // \"en-US\"\n\nconst i18n = await I18n.preload(\n // language sub-tag is matched\n detectLang([\"en\", \"zh-CN\"]) || \"zh-TW\", // \"en\"\n lang => import(`./locales/${lang}.json`),\n);\n```\n\n### Message Formatting\n\nMessage keys are surrounded by double curly brackets:\n\n```ts\nimport { I18n, type Locales } from \"@embra/i18n\";\n\nconst locales: Locales = {\n en: {\n stock: {\n fruit: \"apple\",\n },\n fav_fruit: \"I love {{fruit}}\",\n },\n};\n\nconst i18n = new I18n(\"en\", locales);\nconst fruit = i18n.t(\"stock.fruit\"); // apple\ni18n.t(\"fav_fruit\", { fruit }); // I love apple\n```\n\nPlaceholders without a corresponding value are preserved. This allows the remaining placeholders to be processed later, such as by the [`Trans` component](#trans-component):\n\n```ts\ni18n.t(\"fav_fruit\", {}); // I love {{fruit}}\n```\n\nIt also works with array:\n\n```ts\nimport { I18n, type Locales } from \"@embra/i18n\";\n\nconst locales: Locales = {\n en: {\n fav_fruit: \"I love {{0}} and {{1}}\",\n },\n};\n\nconst i18n = new I18n(\"en\", locales);\ni18n.t(\"fav_fruit\", [\"apple\", \"banana\"]); // I love apple and banana\n```\n\n### Pluralization\n\nYou can easily do pluralization with [Modifier Matching](#modifier-matching).\n\n```ts\nimport { I18n, type Locales } from \"@embra/i18n\";\n\nconst locales: Locales = {\n en: {\n apple: \"{{@}} apples\", // fallback\n \"apple@0\": \"No apple\", // matching { \"@\": 0 } or { \"@\": \"0\" }\n \"apple@1\": \"An apple\", // matching { \"@\": 1 } or { \"@\": \"1\" }\n },\n};\n\nconst i18n = new I18n(\"en\", locales);\ni18n.t(\"apples\", { \"@\": 0 }); // No apple\ni18n.t(\"apples\", { \"@\": 1 }); // An apple\ni18n.t(\"apples\", { \"@\": 3 }); // 3 apples\n```\n\n### Modifier Matching\n\nYou can use `@` to match different modifiers.\n\nFor example:\n\n```ts\ni18n.t(\"a.b.c\", { \"@\": \"d\" });\n```\n\nIt will look for `\"a.b.c@d\"` and fallback to `\"a.b.c\"` if not found.\n\nSee [Pluralization](#pluralization) for more examples.\n\n### Reactive I18n\n\n`i18n.lang$`, `i18n.t$` and `i18n.locales$` are subscribable values.\n\nSee [@embra/reactivity](https://github.com/embrajs/reactivity) for more details.\n\n```js\ni18n.lang$.reaction(lang => {\n // logs lang on changed\n console.log(lang);\n});\n\ni18n.lang$.subscribe(lang => {\n // logs lang immediately and on changed\n console.log(lang);\n});\n```\n\n### Namespace\n\nI18n instance is cheap to create. You can create multiple instances for different namespaces.\n\n```ts\nimport { I18n } from \"@embra/i18n\";\n\n// Module Login\nasync function moduleLogin() {\n const i18n = await I18n.preload(\"en\", lang => import(`./locales/login/${lang}.json`));\n\n console.log(i18n.t(\"password\"));\n}\n\n// Module About\nasync function moduleAbout() {\n const i18n = await I18n.preload(\"en\", lang => import(`./locales/about/${lang}.json`));\n\n console.log(i18n.t(\"author\"));\n}\n```\n\n## Hot Module Replacement\n\nTo use [Vite HMR](https://vitejs.dev/guide/api-hmr.html) for locales:\n\n```ts\nconst i18n = await I18n.preload(\"en\", lang => import(`./locales/${lang}.json`));\n\nif (import.meta.hot) {\n import.meta.hot.accept([\"./locales/en.json\", \"./locales/zh-CN.json\"], ([en, zhCN]) => {\n i18n.locales$.set({\n ...i18n.locales,\n en: en?.default || i18n.locales.en,\n \"zh-CN\": zhCN?.default || i18n.locales[\"zh-CN\"],\n });\n });\n}\n```\n\n## Dynamic Import\n\nAlthough you can simply use `import()` to dynamically load locales, with bundler API you can do more.\n\nFor example with Vite you can use [glob import](https://vitejs.dev/guide/features.html#glob-import) to statically get info of all locales.\nThis way allows you to add or remove locales without changing source code.\n\n```ts\nimport { I18n, detectLang, type Locale, type LocaleLang } from \"@embra/i18n\";\n\nexport const i18nLoader = (): Promise => {\n const localeModules = import.meta.glob(\"./locales/*.json\", { import: \"default\" });\n\n const localeLoaders = Object.keys(localeModules).reduce(\n (loaders, path) => {\n if (localeModules[path]) {\n const langMatch = path.match(/\\/([^/]+)\\.json$/);\n if (langMatch) {\n loaders[langMatch[1]] = localeModules[path];\n }\n }\n return loaders;\n },\n {} as Record Promise>,\n );\n\n const langs = Object.keys(localeLoaders);\n\n return I18n.preload(detectLang(langs) || (localeLoaders.en ? \"en\" : langs[0]), lang => localeLoaders[lang]());\n};\n```\n\n## React\n\n- `` to provide `i18n` context for descendant components.\n- `useTranslate` hook to subscribe and get the latest `i18n.t`.\n- `useLang` hook to subscribe and get the latest `i18n.lang`.\n- `useI18n` hook to subscribe and get the latest `i18n` instance.\n- `` component to insert React elements into translation template messages.\n\n```tsx\nimport { I18n } from \"@embra/i18n\";\nimport { I18nProvider, useTranslate } from \"@embra/i18n/react\";\n\nconst i18n = new I18n(\"en\", { en: { fruit: \"apple\" } });\n\nconst MyComponent = () => {\n const t = useTranslate();\n return
{t(\"fruit\")}
;\n};\n\nconst App = () => {\n return (\n \n \n \n );\n};\n```\n\n### Cascading I18nProvider\n\nYou can nest multiple ``s to create cascading i18n contexts.\n\n```tsx\nimport { I18n } from \"@embra/i18n\";\nimport { I18nProvider, useTranslate } from \"@embra/i18n/react\";\n\nconst baseI18n = new I18n(\"en\", { en: { confirm: \"Confirm\" } });\nconst loginI18n = new I18n(\"en\", { en: { login: \"Login\" } });\n\nconst MyComponent = () => {\n const t = useTranslate();\n return (\n
\n \n \n
\n );\n};\n\nconst App = () => {\n return (\n \n \n \n \n \n );\n};\n```\n\n### Trans Component\n\nTo insert React elements into the translation message:\n\n```tsx\nimport { I18n, I18nProvider } from \"@embra/i18n\";\nimport { Trans, useTranslate } from \"@embra/i18n/react\";\n\nconst locales = {\n en: {\n author: \"CRIMX\",\n fruit: \"apple\",\n eat: \"{{name}} eats {{fruit}}.\",\n },\n};\n\nconst i18n = new I18n(\"en\", locales);\n\nconst MyComponent = () => {\n const t = useTranslate();\n\n return (\n \n {t(\"author\")}\n \n {t(\"fruit\")}\n \n \n );\n};\n\nconst App = () => {\n return (\n \n \n \n );\n};\n```\n\n↓Outputs:\n\n```tsx\n<>\n CRIMX eats apple.\n<>\n```\n\n`data-t-slot` can be ignored if there is only one placeholder.\n\n```tsx\n\n
\n```\n\n`fallback` is used as the default language when `lang` is omitted and as the fallback language when a key is missing.\n\nUse the Astro `` component when a translated message needs Astro slots:\n\n```astro\n---\nimport { createStaticI18n, Trans } from \"@embra/i18n/astro\";\n\nconst { getT } = createStaticI18n({ locales, fallback: \"en\" });\nconst t = getT(Astro.params.lang);\n---\n\n\n {t(\"author\")}\n {t(\"fruit\")}\n\n```\n\n↓Outputs:\n\n```html\nCRIMX eats apple.\n```\n\nThe default slot can be used when there is only one placeholder:\n\n```astro\n\n B\n\n```\n\n`@embra/i18n/astro` is rendered by Astro at build time or on the server. It does not add client-side language switching by itself; use a framework island if the translated component needs to update in the browser.\n\n## VSCode Extension\n\n`@embra/i18n` is compatible with [i18n Ally](https://github.com/lokalise/i18n-ally), a popular VSCode extension for i18n. You can use it to manage your locale files.\n\n## For AI Coding Agents\n\n`@embra/i18n` includes an [llms.txt](./llms.txt) quick guide for AI coding agents.\n\nAdd this to `AGENTS.md` or `CLAUDE.md` in projects that should implement i18n with `@embra/i18n`:\n\n```md\nImplement internationalization with `@embra/i18n`. Usage reference: `node_modules/@embra/i18n/llms.txt`.\n```\n","readmeFilename":"README.md"}
![](\"https://raw.githubusercontent.com/embrajs/i18n/main/assets/logo.svg\"){kind=logo}
\n