@docx-editor.dev/i18n

@docx-editor.dev/i18n

Translate docx-editor.dev controls with locale strings, types, and runtime helpers. The package provides twelve languages and falls back to English for missing translations.

Quick start

Install the locale package:

npm install @docx-editor.dev/i18n

Pass a locale to the editor. This example requires the React adapter and its engine peer:

import { DocxEditor } from '@docx-editor.dev/react';
import { es } from '@docx-editor.dev/i18n';

<DocxEditor document={bytes} i18n={es} locale="es-ES" />;

The i18n prop translates controls. Set locale separately for regional date input and generated document labels. It defaults to en-US.

To share a locale across editors and custom controls, use LocaleProvider:

import { DocxEditor, LocaleProvider } from '@docx-editor.dev/react';
import { de } from '@docx-editor.dev/i18n';

<LocaleProvider i18n={de}>
  <DocxEditor document={bytes} />
</LocaleProvider>;

Custom controls read the same catalog through useTranslation().

Mix a community locale with custom overrides:

import { de } from '@docx-editor.dev/i18n';

const myLocale = {
  ...de,
  formattingBar: { ...de.formattingBar, bold: 'Fettdruck' },
};

Missing or null keys keep the inherited catalog value. Without an outer LocaleProvider, they fall back to English.

Available locales

BCP-47 codes (pt-BR, zh-CN) use camelCase JS identifiers (ptBR, zhCN). For runtime lookup by tag:

import { locales } from '@docx-editor.dev/i18n';

<LocaleProvider i18n={locales[userPreferredLocale]}>
  <DocxEditor document={bytes} />
</LocaleProvider>;

Importing locales includes every locale in your bundle. Import individual locales to reduce the bundle size.

Per-locale subpaths

If you choose a locale at runtime, import its subpath to load only that locale. Static imports include it in the bundle. Dynamic imports let the bundler create a separate chunk:

// Static import: include only this locale's strings.
import pl from '@docx-editor.dev/i18n/pl';

For on-demand loading, use a dynamic import instead:

const pl = (await import('@docx-editor.dev/i18n/pl')).default;

Subpaths ship for every locale: /en, /de, /es, /fr, /he, /hi, /id, /ja, /pl, /pt-BR, /tr, /zh-CN. Each also exports its locale as a named binding (import { pl } from '@docx-editor.dev/i18n/pl') for callers that prefer non-default imports.

Types

Import types to describe locale data and translation functions:

import type {
  LocaleStrings, // shape of `en`, the full source of truth
  PartialLocaleStrings, // shape of a community partial (null falls back)
  Translations, // alias for PartialLocaleStrings
  TranslationKey, // 'formattingBar.bold' | 'navigation.find.counter' | ...
  LocaleCode, // 'en' | 'de' | 'pt-BR' | ...
  TFunction, // signature of the `t()` callback
} from '@docx-editor.dev/i18n';

Outside the React adapter

Build a typed t() outside the adapter packages:

import { createT, deepMerge, en, de, type LocaleStrings } from '@docx-editor.dev/i18n';

const merged = deepMerge(en, de) as LocaleStrings;
const t = createT(merged, 'de');
t('formattingBar.bold'); // 'Fett'
t('navigation.find.total', { total: 15 }); // ICU plurals

en.json is the source of truth. Add keys there, then run bun run i18n:fix from the repo root to sync community locales (new keys land as null). Full guide: docs/i18n.md.

Contributing

The catalogs contain editor controls. Examples keep English text in examples/shared/example-text.ts.

If you use collaborationDemo, documentRefresh, anchorNavigation, or writerAgent keys, move those messages into your application's text catalog. Also move toolbar.exportPdfServerUnavailable. These keys are removed from LocaleStrings and TranslationKey.

To contribute, see CONTRIBUTING.md for setup, tests, and the one-time CLA signature.

Commercial support

For commercial support or custom features, email the support team.