@docx-editor.dev/i18n

catalogDirectionfunctionSource ↗

The writing direction of a locale catalog: its _dir when that is 'ltr' or 'rtl', otherwise the direction of its _lang tag. A catalog that declares neither returns undefined, so a provider can keep the direction it inherits.

The shipped Arabic and Hebrew catalogs declare _dir: 'rtl'. Declare it in your own catalog to mirror the editor chrome for another right-to-left language.

declare function catalogDirection(catalog: {
    readonly _lang?: unknown;
    readonly _dir?: unknown;
} | null | undefined): 'ltr' | 'rtl' | undefined;

chromeDirectionfunctionSource ↗

The direction a locale provider decides for the editor chrome: its dir prop, then the catalog's _dir, then a right-to-left _lang, then the direction an outer provider decided. A left-to-right _lang alone decides nothing, so the shipped left-to-right catalogs keep the host page direction. undefined means the chrome inherits the host page.

Both editor adapters use this rule, so a custom provider of your own can match them.

declare function chromeDirection(dir: 'ltr' | 'rtl' | undefined, catalog: {
    readonly _lang?: unknown;
    readonly _dir?: unknown;
} | null | undefined, inherited: 'ltr' | 'rtl' | undefined): 'ltr' | 'rtl' | undefined;

createTfunctionSource ↗

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

- **Lookup**: dot-notation paths against the locale tree ('formattingBar.bold', 'navigation.find.counter'). - **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 '@docx-editor.dev/i18n';
const merged = deepMerge(en, de) as LocaleStrings;
const t = createT(merged, 'de');
t('formattingBar.bold');                    // → 'Fett'
t('navigation.find.counter', { current: 3, total: 15 });
```

deepMergefunctionSource ↗

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;

isApplePlatformfunctionSource ↗

Whether this browser is running on an Apple platform.

userAgentData.platform first — it is the un-deprecated answer and is not frozen the way navigator.platform is. Both are absent under SSR and in a bare test environment, where the answer is false and the Windows spelling renders: a shortcut that reads "Ctrl+C" on a Mac is wrong, and one that reads "⌘C" in a server render that then hydrates on Windows is worse, because it is wrong AND it flickers.

declare function isApplePlatform(): boolean;

localeDirectionfunctionSource ↗

The writing direction of a BCP-47 language tag: 'rtl' for Arabic, Hebrew, Persian, Urdu, and other right-to-left languages, 'ltr' otherwise. A script subtag decides when present, so az-Arab is right to left and ku-Latn is left to right. An absent or malformed tag is left to right.

The editor adapters read the active catalog's _lang with this function and mirror their controls for a right-to-left catalog. Composed hosts that render their own wrapper can call it to set dir on that wrapper:

tsx <div dir={localeDirection(ar._lang)}>...</div>

declare function localeDirection(tag: string | null | undefined): 'ltr' | 'rtl';

localizeDisabledReasonfunctionSource ↗

Translate a known engine refusal for adapter chrome.

Unknown diagnostics stay exact, so integrations never lose the engine's explanation.

declare function localizeDisabledReason(reason: string | null, t: TFunction): string | null;

platformShortcutfunctionSource ↗

Rewrite the modifier names in a resolved label for this platform.

A no-op everywhere except Apple platforms, and a no-op there too for a string that names no chord — so it is safe to run over every label, including the ones that are not shortcuts at all (a control's plain name passes through untouched).

declare function platformShortcut(text: string): string;

DeepPartialtypeSource ↗

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;
};

LocaleCodetypeSource ↗

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' | 'ar' | 'de' | 'es' | 'fr' | 'he' | 'hi' | 'id' | 'ja' | 'pl' | 'pt-BR' | 'ru' | 'tr' | 'zh-CN';

LocaleStringstypeSource ↗

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;

PartialLocaleStringstypeSource ↗

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 & {});
    _dir?: 'ltr' | 'rtl' | (string & {});
};

TFunctiontypeSource ↗

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;

TranslationKeytypeSource ↗

Every valid dot-notation key into LocaleStrings, e.g. 'formattingBar.bold' or 'navigation.find.counter'. Pass to t(key, vars?) for compile-time-checked translation lookup.

type TranslationKey = DotPath<LocaleStrings>;

TranslationstypeSource ↗

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

type Translations = PartialLocaleStrings;

arconstSource ↗

Arabic (ar). Community-maintained; null leaves fall back to English.

ar: PartialLocaleStrings

deconstSource ↗

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

de: PartialLocaleStrings

enconstSource ↗

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

en: LocaleStrings

esconstSource ↗

Spanish (es). Community-maintained; null leaves fall back to English.

es: PartialLocaleStrings

frconstSource ↗

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

fr: PartialLocaleStrings

heconstSource ↗

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

he: PartialLocaleStrings

hiconstSource ↗

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

hi: PartialLocaleStrings

idconstSource ↗

Indonesian (id). Community-maintained; null leaves fall back to English.

id: PartialLocaleStrings

jaconstSource ↗

Japanese (ja). Community-maintained; null leaves fall back to English.

ja: PartialLocaleStrings

localesconstSource ↗

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>

plconstSource ↗

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

pl: PartialLocaleStrings

ptBRconstSource ↗

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

ptBR: PartialLocaleStrings

ruconstSource ↗

Russian (ru). Community-maintained; null leaves fall back to English.

ru: PartialLocaleStrings

trconstSource ↗

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

tr: PartialLocaleStrings

zhCNconstSource ↗

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

zhCN: PartialLocaleStrings