@deijose/nix-i18n

Internationalization library for Nix.js built on signals and stores.

Features

• Reactive translations powered by Nix.js signals.
• Zero runtime dependencies (uses native Intl API).
• Small bundle size (~4-5 KB typical).
• Type-safe keys and interpolation parameters.
• Multiple backends: inline objects, JSON files, API.
• Lazy-loaded namespaces.
• Pluralization, contexts, and namespaces.
• Date, number, currency, relative time, and list formatting.
• Optional plugins for persistence, locale detection (URL, path, navigator, storage), router integration, form validation, head tags, cross-tab sync, ICU pluralization, and dev overlay for missing keys.
• Optional provide/inject support for sub-trees and tenants.
• CLI to extract and generate translation keys from source files.

Installation

npm install @deijose/nix-i18n

Peer dependency:

npm install @deijose/nix-js

Quick start

import { createI18n } from "@deijose/nix-i18n";
import { html } from "@deijose/nix-js";

const i18n = createI18n({
  locale: "es",
  fallbackLocale: "en",
  messages: {
    es: { hello: "Hola {name}" },
    en: { hello: "Hello {name}" },
  },
});

function App() {
  return html`
    <h1>${i18n.t("hello", { name: "Deiver" })}</h1>
    <button @click=${() => i18n.setLocale("en")}>English</button>
  `;
}

Pluralization

Use the pipe syntax for plural forms:

{
  "items": "No items | One item | {count} items"
}

i18n.t("items", { count: 5 }); // "5 items"

Nested fallback

const i18n = createI18n({
  locale: "es",
  nestedFallback: true,
  messages: {
    es: {
      auth: { login: "Acceder" },
    },
  },
});

i18n.t("auth.login.title"); // "Acceder" fallback desde "auth.login"

Namespaces

const auth = i18n.useNamespace("auth");
auth.t("login.title"); // resolves "auth:login.title"

Or use the key directly:

i18n.t("auth:login.title");

Backends

JSON backend

import { jsonBackend } from "@deijose/nix-i18n/backends/json";

const i18n = createI18n({
  locale: "es",
  backend: jsonBackend({
    baseUrl: "/locales",
    namespaces: ["common", "auth"],
  }),
});

Loads /locales/es/common.json, /locales/en/common.json, etc.

API backend

import { apiBackend } from "@deijose/nix-i18n/backends/api";

const i18n = createI18n({
  locale: "es",
  backend: apiBackend({
    url: "/api/translations",
    headers: { Authorization: "Bearer ..." },
  }),
});

Formatters

All formatters use the Intl API and react to locale changes.

i18n.d(new Date(), { dateStyle: "long" });
i18n.nFormat(1234.5, { maximumFractionDigits: 2 });
i18n.c(99.9, "USD");
i18n.rt(-1, "day");
i18n.list(["a", "b", "c"], { type: "conjunction" });

Plugins

Persist locale

import { persistLocalePlugin } from "@deijose/nix-i18n/plugins/persist";

persistLocalePlugin(i18n, { key: "app-locale" });

Detect locale

import { detectLocalePlugin } from "@deijose/nix-i18n/plugins/detect";

detectLocalePlugin(i18n, {
  order: ["localStorage", "navigator", "fallback"],
});

Router integration

import { routerLocalePlugin } from "@deijose/nix-i18n/plugins/router";

routerLocalePlugin(i18n, router, { mode: "query" });

Head tags

import { headPlugin } from "@deijose/nix-i18n/plugins/head";

headPlugin(i18n, {
  lang: true,
  dir: "auto",
  meta: [{ name: "description", content: (locale) => descriptions[locale] }],
});

Cross-tab sync

import { syncLocalePlugin } from "@deijose/nix-i18n/plugins/sync";

syncLocalePlugin(i18n);

Form validation

import { formValidationPlugin } from "@deijose/nix-i18n/plugins/forms";

const validators = formValidationPlugin(i18n, {
  required: () => (value) => value ? undefined : "required",
  minLength: (n) => (value) => String(value).length < n ? "minLength" : undefined,
}, { keyPrefix: "errors" });

ICU pluralization

import { icuPluralizePlugin } from "@deijose/nix-i18n/plugins/icuPluralize";

icuPluralizePlugin(i18n);

const messages = {
  en: { items: "{count, plural, one {# item} other {# items}}" },
};

i18n.t("items", { count: 5 }); // "5 items"

Dev overlay

import { devOverlayPlugin } from "@deijose/nix-i18n/plugins/devOverlay";

devOverlayPlugin(i18n, { log: true, overlay: true });

CLI

Extract translation keys from source files:

npx nix-i18n-extract src --output extracted-keys.json

Generate a JSON translation file with empty values for multiple locales:

npx nix-i18n-generate src --locales es,en --output translations.json

TypeScript

const i18n = createI18n({
  locale: "es",
  messages: {
    es: { hello: "Hola {name}" },
  },
});

i18n.t("hello", { name: "Deiver" }); // OK
i18n.t("helo"); // Type error
i18n.t("hello"); // Type error: missing `name`

License

MIT