tanzlate (Vanilla JS)

@tanzlate/vanilla is the framework-agnostic layer: it initializes i18next and exposes the namespace-scoped translation helpers. Component interpolation lives in the framework packages — the parser is in @tanzlate/vue, not here.

Package	What it holds
@tanzlate/core	Formatter types and translation-helpers. No i18next runtime
@tanzlate/vanilla	i18next runtime: useCoreContext, initI18nConfig
@tanzlate/vue	Vue layer: I18nProvider, useI18n, <Tanzlate>, registry

You install the layer you need — @tanzlate/vue brings the other two with it.

Installation

npm

npm install @tanzlate/vanilla

yarn

yarn add @tanzlate/vanilla

pnpm

pnpm add @tanzlate/vanilla

Usage

import { useCoreContext } from '@tanzlate/vanilla';

const ctx = await useCoreContext({
  config: {
    namespace: 'app_namespace',
    lng: 'en',
    fallbackLng: 'en',
    supportedLanguages: ['en', 'de'],
    resources: { en: EN_TRANSLATION, de: DE_TRANSLATION },
  },
  ssr: false, // required outside a browser -- see the warning below
});

const tanz = ctx.composeHelper('home');

tanz('welcome'); // → "Welcome to tanzlate"
await ctx.lang('de');

ssr defaults to typeof window === 'undefined'

Which means it is true in any Node process, and useCoreContext then returns a no-op stub whose composeHelper yields '' for every key. Nothing throws and nothing warns. Outside a browser you must pass ssr: false explicitly.

The stub exists for SSR hydration — the server renders a stub, the client hydrates the real context. It is not meant as a permanent state.

Server-side and concurrent use

@tanzlate/vanilla is built around a client app's lifecycle: one active language on one shared instance, mutated by lang() and observed through onLangChange(). On a backend serving concurrent requests in different locales, mutating that shared language is a race.

For that case use @tanzlate/core directly with your own i18next instance, and pass lng per call instead of ever changing the active language:

import { i18nFormatterHelper } from '@tanzlate/core';
import i18next from 'i18next';

const instance = i18next.createInstance();
await instance.init({ fallbackLng: 'en', resources });

const { translationHelper } = i18nFormatterHelper(instance);
const tanz = translationHelper('home');

tanz('welcome', { lng: 'de' });

Missing keys

A missing key returns the prefixed lookup key itself, not '' and not the bare key:

ctx.composeHelper('countries')('Japan'); // → "countries.Japan" if the key is missing

Guard with the underlying instance when that matters: ctx.i18nApp.exists('ns:key', { lng }).

Member	Type	Description
i18nApp	i18n	The i18next instance
composeHelper	(context: string) => TFunc	Translation helper for a context
lang	(lng?: string) => Promise<void>	Change language
onLangChange	(cb) => () => void	Subscribe; returns an unsubscribe

See Utility Functions and Types.