Package Exports

val-i18n
val-i18n/dist/main.js
val-i18n/dist/main.mjs

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (val-i18n) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

val-i18n

Reactive i18n with val-i18n.

Install

npm add val-i18n value-enhancer

Features

Subscribable reactive i18n$ and t$.
Lightweight and fast t() translation.
Nested locale messages.
Message formatting and pluralization.
Easy dynamic locale loading.
Framework integration friendly (React, Svelte, etc.).

Usage

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

With dynamic locales:

import { I18n } from "val-i18n";

const i18n = await I18n.load("en", lang => import(`./locales/${lang}.json`));

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.load(
  // 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:

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

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

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

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

Reactive I18n

i18n.i18n$ and i18n.t$ are subscribable values.

See value-enhancer for more details.

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>

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

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.