@docx-editor.dev/i18n

Use locale catalogs to translate editor controls in React and Vue. Both adapters accept the catalog through the i18n prop.

npm install @docx-editor.dev/i18n

Add this package as a direct dependency when importing its catalogs, including for the editor's i18n prop.

UI language and date input

i18n supplies UI translations; locale selects regional date input and generated document labels. Neither setting infers the other. UI strings default to English or an inherited catalog; locale defaults to en-US.

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

// English UI, Polish dates (with no inherited catalog)
<DocxEditor document={bytes} locale="pl-PL" />;

// Polish UI, Polish dates
<DocxEditor document={bytes} locale="pl-PL" i18n={pl} />;

In Vue, use locale="pl-PL" and :i18n="pl" on <DocxEditor>. For composed editors, wrap Root and its chrome in LocaleProvider; Root has no i18n prop. See the React and Vue examples. See form fields for supported date input.

Available locales

Choose an import style:

• Use named exports for a fixed set of locales: import { es } from '@docx-editor.dev/i18n'. Hyphenated codes (pt-BR, zh-CN) use camelCase exports (ptBR, zhCN).
• Use a dynamic subpath import to load a locale on demand: (await import('@docx-editor.dev/i18n/es')).default. A static subpath import includes that locale in your bundle.

Verify what your installed version ships:

ls node_modules/@docx-editor.dev/i18n/

Set the editor language

Pass the catalog to i18n. These examples use Spanish controls and Spanish regional date input:

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

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

<script setup lang="ts">
import { DocxEditor } from '@docx-editor.dev/vue';
import { es } from '@docx-editor.dev/i18n';
</script>

<template>
  <DocxEditor :document="bytes" :i18n="es" locale="es-ES" />
</template>

To share a catalog across editors, use LocaleProvider:

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

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

<script setup lang="ts">
import { DocxEditor, LocaleProvider } from '@docx-editor.dev/vue';
import { pl } from '@docx-editor.dev/i18n';
</script>

<template>
  <LocaleProvider :i18n="pl">
    <DocxEditor :document="bytes" />
  </LocaleProvider>
</template>

Each catalog overrides the inherited catalog one key at a time. Without an outer provider, missing or null values fall back to English. Nested providers keep inherited values for keys they omit or set to null.

Custom controls read the same catalog through useTranslation():

import { useTranslation } from '@docx-editor.dev/react';

function BoldLabel() {
  const { t } = useTranslation();
  return <span>{t('formattingBar.bold')}</span>;
}

<script setup lang="ts">
import { useTranslation } from '@docx-editor.dev/vue';

const { t } = useTranslation();
</script>

<template>
  <span>{{ t('formattingBar.bold') }}</span>
</template>

Next steps

• Contributing a translation: add or improve a locale with one JSON file
• i18n API reference
• React API reference and Vue API reference