@stackkit-translate/vue

Vue 3 bindings for runtime JSON i18n, built on @stackkit-translate/core. TranslateProvider and useTranslate() composable with ngx-translate-style APIs (use, setTranslation, reloadLang, resetLang, fallback language, and interpolation).

Current release: 1.1.0 — Depends on @stackkit-translate/core ^1.1.0 and optional peer @stackkit-translate/enterprise ^1.1.0 (enterprise modules are licence-gated at runtime). See monorepo CHANGELOG.

Live demo & docs: stackkit-translate docs — interactive demo and Vue API guide.

What's new in 1.1.0

• TranslateProvider — Vue 3 provider component; sets document.documentElement.lang and dir on init and langChange.
• useTranslate() — Composition API composable returning reactive t(), lang, and the underlying engine (i18n).
• Optional licenseKey on provider props for enterprise modules (ICU, missing-report, hot-reload, TMS, SSR).
• Re-exports public symbols from @stackkit-translate/core (types, getDirection, plugins).

Ships as ESM TypeScript declarations. Works with Vue 3.3+ (vue peer dependency). Pair with @stackkit-translate/http for lazy JSON locales.

Keywords: translate i18n vue vue3 composition-api composable ngx-translate localization

Install

npm install @stackkit-translate/core @stackkit-translate/vue @stackkit-translate/http
# Peer dep: vue ^3.3
# Optional enterprise features (optional peer; enable with licence key):
# npm install @stackkit-translate/enterprise
# Pass licenseKey on TranslateProvider to unlock ICU, missing-report, hot-reload, TMS, SSR.

Usage — provider + composable

<script setup lang="ts">
import { TranslateProvider, useTranslate } from "@stackkit-translate/vue";
import { createFetchLoader } from "@stackkit-translate/http";

const loader = createFetchLoader({ prefix: "/assets/i18n/", suffix: ".json" });
</script>

<template>
  <TranslateProvider lang="en" fallback-lang="en" :loader="loader">
    <Greeting />
  </TranslateProvider>
</template>

<script setup lang="ts">
import { useTranslate } from "@stackkit-translate/vue";

const { t, lang, i18n } = useTranslate();
</script>

<template>
  <h1>{{ t("DEMO.WELCOME", { name: "Ada" }) }}</h1>
  <p>Current lang: {{ lang }}</p>
  <button type="button" @click="i18n.use('fr')">Français</button>
</template>

Usage — in-memory locales

<TranslateProvider
  lang="en"
  :translations="{
    en: { HELLO: 'Hello' },
    fr: { HELLO: 'Bonjour' }
  }"
>
  <App />
</TranslateProvider>

Usage — language switcher

<script setup lang="ts">
import { useTranslate } from "@stackkit-translate/vue";

const { t, i18n } = useTranslate();

async function switchLang(code: string): Promise<void> {
  await i18n.use(code);
}
</script>

<template>
  <button v-for="code in ['en', 'fr', 'de']" :key="code" type="button" @click="switchLang(code)">
    {{ code }}
  </button>
  <p>{{ t("DEMO.WELCOME", { name: "Ada" }) }}</p>
</template>

Guide: Migrating from ngx-translate (Angular-focused; Vue uses the same core and loader patterns).

Usage — enterprise licence key

<script setup lang="ts">
import { TranslateProvider } from "@stackkit-translate/vue";
import { createFetchLoader } from "@stackkit-translate/http";
import { TRANSLATE_DEMO_LICENSE_KEY } from "@stackkit-translate/enterprise";

const loader = createFetchLoader({ prefix: "/assets/i18n/", suffix: ".json" });
</script>

<template>
  <TranslateProvider lang="en" :loader="loader" :license-key="TRANSLATE_DEMO_LICENSE_KEY">
    <App />
  </TranslateProvider>
</template>

Unlocks ICU, missing-key reporting, hot-reload, TMS sync, and SSR helpers when modules are entitled. Demo key ships in @stackkit-translate/enterprise for local prototypes only.

API

TranslateProvider (props)

| Prop | Description | | --- | --- | | lang | Initial locale id (default "en"). Watches prop changes and calls use(lang). | | fallbackLang | Fallback locale when a key is missing. | | loader | Async loader from @stackkit-translate/http (e.g. createFetchLoader()). | | translations | Inline locale trees instead of a loader. | | licenseKey | Enterprise licence key; requires @stackkit-translate/enterprise. | | instance | Inject an existing TranslateInstance (testing / SSR). |

Also accepts core engine options: compiler, parser, missingTranslationHandler, missingReporter, reportMissingKeys, extend.

useTranslate()

| Return | Description | | --- | --- | | t(key, params?) | Reactive translation function; re-renders on langChange / translationChange. | | lang | Readonly ref of the current locale id. | | i18n | Underlying TranslateInstance — use(), setTranslation(), getCurrentLang(), events. | | ready | Always true once the composable is mounted inside a provider. |

Re-exports public symbols from @stackkit-translate/core (types, getDirection, plugins).

Vue vs Angular / React naming

| Vue | Angular | React | | --- | --- | --- | | useTranslate().t | TranslateService.instant() / pipe | useTranslate().t | | TranslateProvider | provideTranslateService() | TranslateProvider | | useTranslate().i18n.use(lang) | translate.use(lang) | i18n.use(lang) |

Browser support

Requires a modern browser with ES modules. For SSR, use createSsrSnapshot() / createSsrTranslate() from @stackkit-translate/enterprise to hydrate without a flash of raw keys.

Related packages

• @stackkit-translate/core — framework-agnostic engine (dependency).
• @stackkit-translate/http — createFetchLoader(), multi-file and namespace loaders.
• @stackkit-translate/enterprise — licence flags, ICU, SSR, TMS, audit export.
• @stackkit-translate/angular — Angular service, pipe, directive on the same core.
• @stackkit-translate/react — React provider on the same core.
• @stackkit-translate/js — vanilla bindDom() host and <tr-translate> web component.
• @stackkit-translate/testing — Playwright i18n locators.

License

MIT