val-i18n

Reactive i18n with val-i18n.

Install

npm add val-i18n value-enhancer
Copy

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.
• Framework integration friendly (React, Svelte, etc.).

Usage

Create an I18n instance with static locales:

import { I18n, type Locales } from "val-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 });
Copy

You can also create an I18n instance with preloaded dynamic locales:

import { I18n } from "val-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
Copy

Detect Language

You can detect language of browser/nodejs via detectLang. BCP 47 tags and sub-tags are supported.

import { detectLang } from "val-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`)
);
Copy

Message Formatting

Message keys are surrounded by double curly brackets:

import { I18n, type Locales } from "val-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
Copy

It also works with array:

import { I18n, type Locales } from "val-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
Copy

Pluralization

Message formatting supports a special key :option whose value will be appended to the key-path.

For example:

i18n.t("a.b.c", { ":option": "d" });
Copy

It will look for "a.b.c.d" and fallback to "a.b.c.other" if not found.

So for pluralization we can simply use :option as number count.

import { I18n, type Locales } from "val-i18n";

const locales: Locales = {
  en: {
    apples: {
      0: "No apple",
      1: "An apple",
      other: "{{:option}} apples",
    },
  },
};

const i18n = new I18n("en", locales);
i18n.t("apples", { ":option": 0 }); // No apple
i18n.t("apples", { ":option": 1 }); // An apple
i18n.t("apples", { ":option": 3 }); // 3 apples
Copy

Reactive I18n

i18n.lang$, i18n.t$ and i18n.locales$ are subscribable values.

See value-enhancer for more details.

i18n.lang$.reaction(lang => {
  // logs lang on changed
  console.log(lang);
});

i18n.lang$.subscribe(lang => {
  // logs lang immediately and on changed
  console.log(lang);
});
Copy

Namespace

I18n instance is cheap to create. You can create multiple instances for different namespaces.

import { I18n } from "val-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"));
}
Copy

Hot Module Replacement

To use Vite HMR for locales:

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"],
      });
    }
  );
}
Copy

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 to statically get info of all locales. This way allows you to add or remove locales without changing source code.

import { I18n, detectLang, type Locale, type LocaleLang } from "val-i18n";

export const i18nLoader = (): Promise<I18n> => {
  const localeModules = import.meta.glob<boolean, string, Locale>(
    "./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<LocaleLang, () => Promise<Locale>>);

  const langs = Object.keys(localeLoaders);

  return I18n.preload(
    detectLang(langs) || (localeLoaders.en ? "en" : langs[0]),
    lang => localeLoaders[lang]()
  );
};
Copy

Framework Integration

Svelte

In Svelte you can just pass i18n.t$ as component props and use $t directly.

<script>
  export let t;
</script>

<div>
  <h1>{$t("title")}</h1>
</div>
Copy

new MySvelteComponent({
  target: document.body,
  props: {
    t: i18n.t$,
  },
});
Copy

You can also set i18n.t$ to a Svelte context.

For more advance usages checkout val-i18n-svelte.

React

It is recommended to also install val-i18n-react which includes some handy hooks.

Or you can just use the hooks for value-enhancer: use-value-enhancer.