[](https://embrajs.github.io/i18n)
[](https://github.com/embrajs/i18n/actions/workflows/build.yml)
[](https://www.npmjs.com/package/@embra/i18n)
[](https://embrajs.github.io/i18n/coverage/)
A lightweight, reactive internationalization library.
## Install
```bash
npm add @embra/reactivity @embra/i18n
```
## Features
- Subscribable reactive `lang$`, `t$` and `locales$`.
- Lightweight and fast `t()` translation.
- Nested locale messages.
- Message formatting and pluralization.
- Easy dynamic locale loading.
- Locale namespaces.
- First-class React support.
## Usage
Create an I18n instance with static locales:
```ts
import { I18n, type Locales } from "@embra/i18n";
const locales: Locales = {
en: {
stock: {
fruit: "apple",
},
},
};
const i18n = new I18n("en", locales);
i18n.t("stock.fruit"); // apple
// add more locales later
const zhCN = await import(`./locales/zh-CN.json`);
i18n.addLocale("zh-CN", zhCN);
// or replace all locales manually
const zhTW = await import(`./locales/zh-TW.json`);
i18n.locales$.set({ "zh-TW": zhTW });
```
You can also create an `I18n` instance with preloaded dynamic locales:
```ts
import { I18n } from "@embra/i18n";
const i18n = await I18n.preload("en", lang => import(`./locales/${lang}.json`));
// Locale `./locales/en.json` is preloaded
await i18n.switchLang("zh-CN"); // Locale `./locales/zh-CN.json` is loaded
```
### Detect Language
You 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.
```ts
import { detectLang } from "@embra/i18n";
detectLang(); // "en-US"
const i18n = await I18n.preload(
// language sub-tag is matched
detectLang(["en", "zh-CN"]) || "zh-TW", // "en"
lang => import(`./locales/${lang}.json`),
);
```
### Message Formatting
Message keys are surrounded by double curly brackets:
```ts
import { I18n, type Locales } from "@embra/i18n";
const locales: Locales = {
en: {
stock: {
fruit: "apple",
},
fav_fruit: "I love {{fruit}}",
},
};
const i18n = new I18n("en", locales);
const fruit = i18n.t("stock.fruit"); // apple
i18n.t("fav_fruit", { fruit }); // I love apple
```
It also works with array:
```ts
import { I18n, type Locales } from "@embra/i18n";
const locales: Locales = {
en: {
fav_fruit: "I love {{0}} and {{1}}",
},
};
const i18n = new I18n("en", locales);
i18n.t("fav_fruit", ["apple", "banana"]); // I love apple and banana
```
### Pluralization
You can easily do pluralization with [Modifier Matching](#modifier-matching).
```ts
import { I18n, type Locales } from "@embra/i18n";
const locales: Locales = {
en: {
apple: "{{@}} apples", // fallback
"apple@0": "No apple", // matching { "@": 0 } or { "@": "0" }
"apple@1": "An apple", // matching { "@": 1 } or { "@": "1" }
},
};
const i18n = new I18n("en", locales);
i18n.t("apples", { "@": 0 }); // No apple
i18n.t("apples", { "@": 1 }); // An apple
i18n.t("apples", { "@": 3 }); // 3 apples
```
### Modifier Matching
You can use `@` to match different modifiers.
For example:
```ts
i18n.t("a.b.c", { "@": "d" });
```
It will look for `"a.b.c@d"` and fallback to `"a.b.c"` if not found.
See [Pluralization](#pluralization) for more examples.
### Reactive I18n
`i18n.lang$`, `i18n.t$` and `i18n.locales$` are subscribable values.
See [@embra/reactivity](https://github.com/embrajs/reactivity) for more details.
```js
i18n.lang$.reaction(lang => {
// logs lang on changed
console.log(lang);
});
i18n.lang$.subscribe(lang => {
// logs lang immediately and on changed
console.log(lang);
});
```
### Namespace
I18n instance is cheap to create. You can create multiple instances for different namespaces.
```ts
import { I18n } from "@embra/i18n";
// Module Login
async function moduleLogin() {
const i18n = await I18n.preload("en", lang => import(`./locales/login/${lang}.json`));
console.log(i18n.t("password"));
}
// Module About
async function moduleAbout() {
const i18n = await I18n.preload("en", lang => import(`./locales/about/${lang}.json`));
console.log(i18n.t("author"));
}
```
## Hot Module Replacement
To use [Vite HMR](https://vitejs.dev/guide/api-hmr.html) for locales:
```ts
const i18n = await I18n.preload("en", lang => import(`./locales/${lang}.json`));
if (import.meta.hot) {
import.meta.hot.accept(["./locales/en.json", "./locales/zh-CN.json"], ([en, zhCN]) => {
i18n.locales$.set({
...i18n.locales,
en: en?.default || i18n.locales.en,
"zh-CN": zhCN?.default || i18n.locales["zh-CN"],
});
});
}
```
## Dynamic Import
Although you can simply use `import()` to dynamically load locales, with bundler API you can do more.
For example with Vite you can use [glob import](https://vitejs.dev/guide/features.html#glob-import) to statically get info of all locales.
This way allows you to add or remove locales without changing source code.
```ts
import { I18n, detectLang, type Locale, type LocaleLang } from "@embra/i18n";
export const i18nLoader = (): Promise => {
const localeModules = import.meta.glob("./locales/*.json", { import: "default" });
const localeLoaders = Object.keys(localeModules).reduce(
(loaders, path) => {
if (localeModules[path]) {
const langMatch = path.match(/\/([^/]+)\.json$/);
if (langMatch) {
loaders[langMatch[1]] = localeModules[path];
}
}
return loaders;
},
{} as Record Promise>,
);
const langs = Object.keys(localeLoaders);
return I18n.preload(detectLang(langs) || (localeLoaders.en ? "en" : langs[0]), lang => localeLoaders[lang]());
};
```
## React
- `` to provide `i18n` context for descendant components.
- `useTranslate` hook to subscribe and get the latest `i18n.t`.
- `useLang` hook to subscribe and get the latest `i18n.lang`.
- `useI18n` hook to subscribe and get the latest `i18n` instance.
- `` component to insert React elements into translation template messages.
```tsx
import { I18n } from "@embra/i18n";
import { I18nProvider, useTranslate } from "@embra/i18n/react";
const i18n = new I18n("en", { en: { fruit: "apple" } });
const MyComponent = () => {
const t = useTranslate();
return
{t("fruit")}
;
};
const App = () => {
return (
);
};
```
### Cascading I18nProvider
You can nest multiple ``s to create cascading i18n contexts.
```tsx
import { I18n } from "@embra/i18n";
import { I18nProvider, useTranslate } from "@embra/i18n/react";
const baseI18n = new I18n("en", { en: { confirm: "Confirm" } });
const loginI18n = new I18n("en", { en: { login: "Login" } });
const MyComponent = () => {
const t = useTranslate();
return (
);
};
const App = () => {
return (
);
};
```
### Trans Component
To insert React elements into the translation message:
```tsx
import { I18n, I18nProvider } from "@embra/i18n";
import { Trans, useTranslate } from "@embra/i18n/react";
const locales = {
en: {
author: "CRIMX",
fruit: "apple",
eat: "{{name}} eats {{fruit}}.",
},
};
const i18n = new I18n("en", locales);
const MyComponent = () => {
const t = useTranslate();
return (
{t("author")}
{t("fruit")}
);
};
const App = () => {
return (
);
};
```
↓Outputs:
```tsx
<>
CRIMX eats apple.
<>
```
`data-t-slot` can be ignored if there is only one placeholder.
```tsx
B
```
↓Outputs:
```tsx
<>
a
B
c
```
## Astro
For static Astro pages, create cached translation helpers and get `t` from the route language:
```astro
---
import { createStaticI18n } from "@embra/i18n/astro";
const locales = {
en: {
title: "Fruit stock",
author: "CRIMX",
fruit: "apple",
eat: "{{name}} eats {{fruit}}.",
},
zh: {
title: "水果库存",
author: "CRIMX",
fruit: "苹果",
eat: "{{name}} 吃 {{fruit}}。",
},
};
const { getT } = createStaticI18n({ locales, fallback: "en" });
const t = getT(Astro.params.lang);
---
{t("title")}
```
`fallback` is used as the default language when `lang` is omitted and as the fallback language when a key is missing.
Use the Astro `` component when a translated message needs Astro slots:
```astro
---
import { createStaticI18n, Trans } from "@embra/i18n/astro";
const { getT } = createStaticI18n({ locales, fallback: "en" });
const t = getT(Astro.params.lang);
---
{t("author")}{t("fruit")}
```
↓Outputs:
```html
CRIMX eats apple.
```
The default slot can be used when there is only one placeholder:
```astro
B
```
`@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.
## VSCode Extension
`@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.
## For AI Coding Agents
`@embra/i18n` includes an [llms.txt](./llms.txt) quick guide for AI coding agents.
Add this to `AGENTS.md` or `CLAUDE.md` in projects that should implement i18n with `@embra/i18n`:
```md
Implement internationalization with `@embra/i18n`. Usage reference: `node_modules/@embra/i18n/llms.txt`.
```
