vanilla-signal-i18n

I18n

I18n is a reactive internationalization manager based on vanilla-signal, with source code located in src/i18n.js. It can create independent instances via new I18n(options) or createI18n(options). It also retains legacy utility functions like setLanguages/getLanguages/getLocale/getLang/t for compatibility with older projects.

It is recommended to use independent instances in new code to avoid sharing global language state across multiple pages or components.

Installation

npm:

npm install vanilla-signal-i18n

script:

<script src="https://unpkg.com/vanilla-signal-i18n/dist/index.umd.js"></script>

Import

// esm
import { I18n, createI18n, defaultI18n, t } from 'vanilla-signal-i18n';

// umd: Global variable `vanillaSignalI18n`
const { I18n, createI18n, defaultI18n, t } = vanillaSignalI18n;

Basic Usage

const i18n = createI18n({
  locale: 'zh-CN',
  fallbackLocale: 'en',
  messages: {
    en: {
      common: {
        confirm: 'Confirm',
        hello: 'Hello {name}',
      },
    },
    zh: {
      common: {
        confirm: '确定',
        hello: '你好 {name}',
      },
    },
  },
});

i18n.t('common.confirm'); // 确定
i18n.t('common.hello', { name: 'World' }); // 你好 World

Keys support dot notation paths. When a translation is not found in the current language, it falls back in the order of zh-cn -> zh -> en. If still not found, the original key is returned.

Reactive Translation

i18n.t() reads internal signals. When called within a vanilla-signal reactive context, changes to locale or messages will automatically trigger re-computation.

import { createEffect } from 'vanilla-signal';

const i18n = new I18n({
  locale: 'en',
  messages: {
    en: { title: 'Settings' },
    zh: { title: '设置' },
  },
});

createEffect(() => {
  document.title = i18n.t('title');
});

i18n.setLocale('zh');

If you only need to read the locale signal, you can also use getLocaleSignal():

const locale = i18n.getLocaleSignal();

createEffect(() => {
  console.log(locale());
});

Appending Language Packs

i18n.addMessages('zh', {
  modal: {
    title: '提示',
    cancel: '取消',
  },
});

i18n.addMessages('en', {
  modal: {
    title: 'Tip',
    cancel: 'Cancel',
  },
});

addMessages(locale, messages) deeply merges with existing language packs by default. To replace the language pack for a specific locale:

i18n.addMessages('zh', { ok: '确定' }, { merge: false });

To replace or merge complete language packs:

i18n.setMessages(
  {
    en: { save: 'Save' },
    zh: { save: '保存' },
  },
  { merge: true }
);

Namespaces

createTranslator(namespace) creates a translation function with a prefix, suitable for use within components.

const modalT = i18n.createTranslator('modal');

modalT('title'); // Equivalent to i18n.t('modal.title')
modalT('confirm');

Missing Translations

By default, missing translations return the original key. You can output warnings via warnMissing or customize the return value via missing.

const i18n = createI18n({
  locale: 'zh',
  fallbackLocale: 'en',
  warnMissing: true,
  missing: ({ key }) => `[missing:${key}]`,
});

Subscribing to Changes

subscribe(handler) listens for changes in locale, fallback locale, and messages, suitable for integration with non-signal code.

const unsubscribe = i18n.subscribe((event) => {
  console.log(event.type, event.locale);
});

i18n.setLocale('zh');
unsubscribe();

Event types:

Type	Triggered When
locale	Current language changes
fallback-locale	Fallback language changes
messages	Language packs are set or appended

Default Instance

defaultI18n is the built-in default instance of the library. Legacy utility functions delegate to it:

import {
  setLanguages,
  getLanguages,
  getLocale,
  getLang,
  t,
} from 'vanilla-signal-i18n';

setLanguages({
  en: { ok: 'OK' },
  zh: { ok: '确定' },
});

t('ok'); // Returns text based on current default locale
getLanguages();
getLocale();
getLang();

t() is also compatible with the old signature:

t(
  'ok',
  {
    en: { ok: 'OK' },
    zh: { ok: '确定' },
  },
  'zh'
); // 确定

For new code requiring interpolation, dynamic language switching, or isolated language states for different components, it is recommended to use the i18n.t() method of an independent I18n instance.

Options

Parameter	Type	Default	Description
locale	string	Auto	Initial language; reads html lang or browser if empty
fallbackLocale	string	'en'	Fallback language
messages	Record<string, Record<string, any>>	{}	Language packs
languages	Record<string, Record<string, any>>	{}	Alias for messages, for backward compatibility
missing	(payload: object) => string	null	Handler function for missing translations
warnMissing	boolean	false	Whether to output warning for missing translations

Instance Properties

The state of I18n is accessed via instance methods; no public properties are exposed for direct modification. messages are shallow/deep cloned upon writing to prevent direct reuse of external object references.

Instance Methods

Method	Description
getLocaleSignal()	Get the signal accessor for the current locale
getLocale()	Get the current locale
setLocale(locale)	Set the current locale
getFallbackLocale()	Get the fallback locale
setFallbackLocale(locale)	Set the fallback locale
setMessages(messages, options)	Set complete language packs
setLanguages(messages)	Compatible alias for setMessages()
addMessages(locale, messages, options)	Append or replace language pack for a specific locale
getMessages(locale)	Get language pack for a specific locale; returns all if no locale provided
getLanguages()	Compatible alias for getMessages()
has(key, options)	Check if a key has an available translation
resolve(key, options)	Resolve translation, returning matched locale and original value
t(key, params, options)	Get translated text and perform interpolation
createTranslator(namespace, defaults)	Create a namespaced translation function
subscribe(handler)	Subscribe to i18n state changes, returns unsubscribe function
destroy()	Clean up listeners and language packs

Translation Value Types

Translation values can be strings, numbers, booleans, or functions.

const i18n = createI18n({
  locale: 'en',
  messages: {
    en: {
      count: ({ value }) => `${value} items`,
    },
  },
});

i18n.t('count', { value: 3 }); // 3 items

Functions receive two parameters:

Parameter	Description
params	Interpolation parameters passed when calling t()
context	{ key, locale, i18n }

Locale Rules

Locales are normalized to lowercase, and _ is converted to -:

i18n.setLocale('zh_CN');
i18n.getLocale(); // zh-cn

When looking up translations, it falls back in the order of full locale, base language, fallback locale, and fallback base language. For example, if the current locale is zh-CN and the fallback locale is en-US, the lookup order is:

zh-cn -> zh -> en-us -> en

Translation

• 中文