i18n

Every export of @kitr/i18n, @kitr/i18n/provider, read from the published type definitions. The guide shows them in use.

@kitr/i18n

Re-exports i18next, react-i18next unchanged, plus the following.

createI18n

function createI18n(config: I18nConfig, initialLocale?: string): i18n;

Creates an isolated i18next instance from your config, already initialised with react-i18next. The locale is initialLocale, else the detected one when detect is on, else defaultLocale.

detectLocale

function detectLocale(supported: string[], storageKey?: string): string | undefined;

In the browser, the saved choice under storageKey in localStorage, else the best match for navigator.languages. Returns undefined on the server or when nothing matches.

matchLocale

function matchLocale(candidates: string | readonly string[], supported: string[]): string | undefined;

Pick the best supported locale from an Accept-Language header (server) or a language list.

defineConfig

const defineConfig: <const C extends I18nConfig>(config: C) => C;

Types config/i18n.ts. Returns the object you pass, unchanged.

I18nConfig

interface I18nConfig extends Omit<InitOptions, 'resources' | 'lng'> {
  /** Every locale's strings, keyed by locale then namespace: `{ en: { common: { hello: 'Hello' } } }`. */
  resources: Record<string, Record<string, Record<string, unknown>>>;
  /** The locale used when nothing better matches, and the fallback for missing keys. */
  defaultLocale: string;
  /** The locales the app supports. Default: the keys of `resources`. */
  locales?: string[];
  /** Detect from `navigator.language` (client) or `Accept-Language` (server). Default true. */
  detect?: boolean;
  /** Query/cookie/storage key for an explicit choice. Default `locale`. */
  storageKey?: string;
}

The options in config/i18n.ts: your strings per locale, the fallback locale and detection. Any other i18next init option passes straight through.

TranslationKeys

type TranslationKeys<R, Prefix extends string = ''> = {
  [K in keyof R & string]: R[K] extends string ? `${Prefix}${K}` : TranslationKeys<R[K], `${Prefix}${K}.`>;
}[keyof R & string];

Keys of a resource bundle as namespace:key.path strings, for typed t().

@kitr/i18n/provider

i18nProvider

const i18nProvider: KitrProvider;

Binds i18n from config/i18n.ts and wraps the tree in I18nextProvider.