Skip to content

Adapter: Translator

i18n covers how translation resolution works day to day. This page is the reference for the port a whole engine swap replaces.

The interface

TypeScript
interface ITranslator {
	t(key: string, vars?: Record<string, string>): string;
	language(): string;
	language(lang: string): Promise<void>;
	addTranslations(bundle: Translations): void;
	translation(lang: string, key: string): string | undefined;
	translation(lang: string, key: string, value: string): void;
	removeTranslations(prefix: string, lang?: string): void;
	dispose(): void;
}

Default implementation

DefaultTranslator is a key + {var} interpolation lookup over a merged bundle table, seeded with the kit’s own core.* strings, English loaded eagerly, every other kit locale loaded lazily the first time language(lang) switches to it. Constructor options (DefaultTranslatorOptions): language (initial tag, default 'en'), translations (initial bundles), loadTranslations (async loader for a tag not yet fetched), onMissingTranslation (custom fallback for an unresolved key), and fallbackLanguage (final-fallback tag, default 'en', pass null to disable and rely solely on the BCP-47 parent chain).

Rules & restrictions

  • removeTranslations(prefix, lang?) is what the kit calls automatically on plugin dispose for plugin.<id>. prefixed keys, a custom engine needs to implement this correctly for plugin translation cleanup to actually work.
  • language(lang) returns a Promise<void> because a real engine may need to await an async loader before the new language’s bundle is ready, callers should await it rather than assuming the switch is synchronous.

How to extend it

Swap the whole engine when you need pluralization, gender, or ICU MessageFormat. When you pass your own translator, the kit uses it as-is and hands it none of the translation config, your engine owns its translation state end to end. So wire translations / loadTranslations / language into your adapter yourself before you pass it, those options only seed the built-in DefaultTranslator:

TypeScript
import nmplayer from '@nomercy-entertainment/nomercy-video-player'; // nomercy-music-player's factory works identically

const player = nmplayer('player');

player.setup({ translator: myI18nextAdapter });

Adapters for i18next and FormatJS are meant to live as separate packages outside the kit (@nomercy/translator-i18next, @nomercy/translator-formatjs), consumers pull only the engine they want.

Next steps

  • Adapter: Cue Parser: the same registry-and-default shape, applied to subtitle and lyric formats.