@eigenpal/docx-editor-i18n

Build a typed `t(key, vars?)` function from a merged locale.

- **Lookup**: dot-notation paths against the locale tree (`'toolbar.bold'`, `'dialogs.findReplace.matchCount'`). - **Interpolation**: `{name}` placeholders read from `vars`. - **Plurals**: ICU `{count, plural, =0 {none} one {# item} other {# items}}` with `Intl.PluralRules` for CLDR categories and `=N` for exact matches. - **Fallback**: missing keys return the key string itself, useful for spotting un-translated UI in development.

The React/Vue adapters wrap this in `useTranslation()`; use it directly when building a non-React/Vue host (server-rendered docs, CLI, etc.).

declare function createT(strings: LocaleStrings, lang?: string): TFunction;

```ts
import { deepMerge, createT, en, de } from '@eigenpal/docx-editor-i18n';
const merged = deepMerge(en, de) as LocaleStrings;
const t = createT(merged, 'de');
t('toolbar.bold');                          // → 'Fett'
t('dialogs.findReplace.matchCount', { current: 3, total: 15 });
```

Deep-merge a partial locale over a base locale. Null leaves in the override are treated as "not translated" and fall back to the base. Adapters call this once when the `i18n` prop changes, then hand the result to [createT](createT).

declare function deepMerge(base: AnyRecord, override: AnyRecord | undefined): AnyRecord;

Recursive Partial that allows `null` at leaves to signal "not yet translated, fall back to English." Community translations use this shape; `bun run i18n:fix` keeps every locale aligned to `en.json` with `null` placeholders for missing keys.

type DeepPartial<T> = {
    [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K] | null;
};

Every locale code shipped from this package. Pass to `locales[code]` for runtime lookup; assign to `_lang` to drive `Intl.PluralRules`.

Custom codes are accepted at runtime ([PartialLocaleStrings._lang](PartialLocaleStrings._lang) widens to any string), but the shipped union is the IDE-completion list.

type LocaleCode = 'en' | 'de' | 'fr' | 'he' | 'hi' | 'pl' | 'pt-BR' | 'tr' | 'zh-CN';

Full locale string set, auto-derived from `en.json` (the source of truth). Every other locale is a `PartialLocaleStrings` against this shape.

type LocaleStrings = typeof enJson;

Partial locale strings — what consumers pass to the editor's `i18n` prop. Missing keys fall back to English. Optional `_lang` carries the BCP-47 tag used by `Intl.PluralRules`; shipped codes autocomplete but custom strings are accepted.

type PartialLocaleStrings = DeepPartial<LocaleStrings> & {
    _lang?: LocaleCode | (string & {});
};

The signature of `t()`: look up a translation by dot-notation key, interpolate `{vars}`, and resolve ICU plurals.

type TFunction = (key: TranslationKey, vars?: Record<string, string | number>) => string;

Every valid dot-notation key into `LocaleStrings`, e.g. `'toolbar.bold'` or `'dialogs.findReplace.matchCount'`. Pass to `t(key, vars?)` for compile-time-checked translation lookup.

type TranslationKey = DotPath<LocaleStrings>;

Alias for `PartialLocaleStrings`. Prefer this name when typing the consumer-facing `i18n` prop or function parameter.

type Translations = PartialLocaleStrings;

German (`de`). Community-maintained; null leaves fall back to English.

de: PartialLocaleStrings

English (`en`) — the source of truth, 100% covered.

en: LocaleStrings

French (`fr`). Community-maintained; null leaves fall back to English.

fr: PartialLocaleStrings

Hebrew (`he`). Community-maintained; null leaves fall back to English.

he: PartialLocaleStrings

Hindi (`hi`). Community-maintained; null leaves fall back to English.

hi: PartialLocaleStrings

Every shipped locale, keyed by BCP-47 tag. Use for runtime locale pickers and "look up the locale matching this user preference" code:

```ts <DocxEditor i18n={locales[userLocale]} /> ```

Importing `locales` defeats the per-locale tree-shake — the bundler sees a static reference to every locale. If you only need one or two, import them by name (`import { en, de } from '...'`) instead.

locales: Record<LocaleCode, PartialLocaleStrings>

Polish (`pl`). Community-maintained; null leaves fall back to English.

pl: PartialLocaleStrings

Portuguese (Brazil) (`pt-BR`). Community-maintained; null leaves fall back to English.

ptBR: PartialLocaleStrings

Turkish (`tr`). Community-maintained; null leaves fall back to English.

tr: PartialLocaleStrings

Simplified Chinese (`zh-CN`). Community-maintained; null leaves fall back to English.

zhCN: PartialLocaleStrings