@stackkit-translate/core

Framework-agnostic runtime i18n engine for JSON locales — createTranslate(), nested keys, {{param}} interpolation, lazy loaders, plugins, and ngx-translate-style APIs (use, setTranslation, reloadLang, resetLang, getBrowserLang).

Current release: 1.0.0 — Foundation for all @stackkit-translate/* adapters. See monorepo CHANGELOG.

Docs & demo: translate docs — interactive demo and API reference.

Ships as ESM with TypeScript declarations. Works in Node 18+ and modern browsers. Framework packages (@stackkit-translate/angular, @stackkit-translate/react, @stackkit-translate/js) depend on this package.

Keywords: translate i18n localization typescript runtime-i18n ngx-translate

Install

npm install @stackkit-translate/core
# Pair with a loader for HTTP JSON:
npm install @stackkit-translate/http

Usage — in-memory locales

import { createTranslate } from "@stackkit-translate/core";

const translate = createTranslate({
  lang: "en",
  fallbackLang: "en",
  translations: {
    en: { HELLO: "Hello, {{name}}!" },
    fr: { HELLO: "Bonjour, {{name}} !" }
  }
});

translate.t("HELLO", { name: "Ada" }); // "Hello, Ada!"
await translate.use("fr");
translate.t("HELLO", { name: "Ada" }); // "Bonjour, Ada !"

Usage — lazy JSON loader

import { createTranslate } from "@stackkit-translate/core";
import { createFetchLoader } from "@stackkit-translate/http";

const translate = createTranslate({
  lang: "en",
  fallbackLang: "en",
  loader: createFetchLoader({ prefix: "/assets/i18n/", suffix: ".json" })
});

await translate.use("fr");
translate.t("HOME.TITLE");

Usage — MessageFormat plugin (community)

import { applyTranslatePlugins, createMessageFormatPlugin, createTranslate } from "@stackkit-translate/core";

const translate = createTranslate({
  lang: "en",
  translations: {
    en: { ITEMS: "{count, plural, one {# item} other {# items}}" }
  },
  plugins: [createMessageFormatPlugin()]
});

API (selected)

| API | Description | | --- | --- | | createTranslate(config) | Create a translation instance. | | translate.t(key, params?) | Synchronous lookup with interpolation. | | translate.use(lang) | Switch active locale (loads via loader when configured). | | translate.setTranslation(lang, tree, merge?) | Merge or replace in-memory translations. | | translate.reloadLang(lang) | Reload from loader. | | translate.resetLang(lang) | Clear cached locale. | | getBrowserLang() | Detect browser language prefix (en from en-US). | | getDirection(lang) | ltr or rtl for document layout. | | createMessageFormatPlugin() | Lightweight plural/select MessageFormat plugin. |

Full surface: API reference.

Related packages

• @stackkit-translate/http — fetch JSON/JS locale files.
• @stackkit-translate/angular — TranslateService, pipe, directive.
• @stackkit-translate/react — TranslateProvider, useTranslate().
• @stackkit-translate/js — vanilla createTranslateHost() and bindDom().
• @stackkit-translate/enterprise — optional ICU, SSR, TMS, audit, and licence gating.
• @stackkit-translate/cli — translate-extract and typegen.

License

MIT