Language and locale

Use i18n for interface labels and locale for regional formatting. Changing labels does not translate document text.

Import a shipped catalog from @docx-editor.dev/i18n. Pass a partial catalog to override selected labels. Missing values retain the inherited catalog, which defaults to English.

The live selector changes packaged toolbar labels. The contract text and application labels stay in English.

DOCX editor language options

Set interface translation and document locale separately. Neither setting translates the document's text.

Shipped locale catalogs

Import only the catalogs your application uses from @docx-editor.dev/i18n. The locales record includes every catalog and therefore includes them all in the bundle.

Community catalogs can contain untranslated entries. Missing values and null values retain the inherited translation. At the top-level provider, the inherited catalog is English. Nested providers can override selected labels without resetting the outer provider's language.

Partial catalogs and custom labels

Use the Translations type for a partial catalog. Keep the existing nested key structure and placeholder names. Set _lang when your custom catalog needs language-specific plural rules. The catalog formatter supports named placeholders and its supported plural message syntax.

useTranslation() returns t and catalogue in both adapters. Use t with a typed TranslationKey and explicit placeholder values. Keep labels such as an application's approval action in the application catalog. Toolbar.Action.label takes resolved text, rather than a catalog key. A host group's literal label takes priority over labelKey.

If a region's t overrides every label, return a useful string for every key it receives. Do not return the key itself as a visible translation. Use the active catalog as a fallback for keys your application does not override.

Live updates and document direction

Changes to Root.locale apply to subsequent edits without replacing the editor instance. Existing stored date formats remain unchanged. Changes to Root.translate update generated labels without replacing the instance. Keep document bytes and font configuration stable when you change interface language.

Interface language does not set paragraph direction. Use document formatting and the left-to-right or right-to-left controls for paragraph direction. Keep language-sensitive font shaping in the font configuration's language field. Use date fields and form controls to verify regional input behavior in your application.

React and Vue reference

Pass your DOCX bytes and loaded fonts to this component. The preview uses a fictional contract.

import { de } from '@docx-editor.dev/i18n';
import { DocxEditor, LocaleProvider, type DocxEditorRootProps } from '@docx-editor.dev/react';
import { reviewModule, DocxEditorReview } from '@docx-editor.dev/pro/react';
import '@docx-editor.dev/core/styles/editor.css';

const modules = [reviewModule()];

export function ContractEditor({
  bytes,
  fonts,
}: {
  bytes: Uint8Array;
  fonts: DocxEditorRootProps['fonts'];
}) {
  return (
    <LocaleProvider i18n={de}>
      <div className="docx-editor contract-workspace">
        <DocxEditor.Root
          document={bytes}
          fonts={fonts}
          modules={modules}
          locale="de-DE"
          author="Demo reviewer"
          mode="suggesting"
          reviewDisplayMode="all-markup"
        >
          <DocxEditor.Toolbar />
          <DocxEditor.Viewport style={{ height: 520 }}>
            <DocxEditor.Content />
            <DocxEditor.HyperLink />
            <DocxEditor.ContextMenu />
            <DocxEditorReview />
          </DocxEditor.Viewport>
        </DocxEditor.Root>
      </div>
    </LocaleProvider>
  );
}

<script setup lang="ts">
import { de } from '@docx-editor.dev/i18n';
import { DocxEditor, LocaleProvider } from '@docx-editor.dev/vue';
import { reviewModule, DocxEditorReview } from '@docx-editor.dev/pro/vue';
import type { FontConfigurationFragment } from '@docx-editor.dev/vue';
import '@docx-editor.dev/core/styles/editor.css';

defineProps<{ bytes: Uint8Array; fonts: FontConfigurationFragment }>();
const modules = [reviewModule()];
</script>

<template>
  <LocaleProvider :i18n="de">
    <div class="docx-editor contract-workspace">
      <DocxEditor.Root
        :document="bytes"
        :fonts="fonts"
        :modules="modules"
        locale="de-DE"
        author="Demo reviewer"
        mode="suggesting"
        review-display-mode="all-markup"
      >
        <DocxEditor.Toolbar />
        <DocxEditor.Viewport :style="{ height: '520px' }">
          <DocxEditor.Content />
          <DocxEditor.HyperLink />
          <DocxEditor.ContextMenu />
          <DocxEditorReview />
        </DocxEditor.Viewport>
      </DocxEditor.Root>
    </div>
  </LocaleProvider>
</template>

Override labels in one region

Mount this toolbar inside your editor root. The nested provider changes two labels and retains the outer provider's other translations. Use the same approach for a menu or review region.

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

const labels: Translations = {
  formattingBar: { bold: 'Bold text', italic: 'Italic text' },
};

export function ContractToolbar() {
  return (
    <LocaleProvider i18n={labels}>
      <DocxEditor.Toolbar preset={false}>
        <DocxEditor.Toolbar.Bold />
        <DocxEditor.Toolbar.Italic />
      </DocxEditor.Toolbar>
    </LocaleProvider>
  );
}

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

const labels: Translations = {
  formattingBar: { bold: 'Bold text', italic: 'Italic text' },
};
</script>

<template>
  <LocaleProvider :i18n="labels">
    <DocxEditor.Toolbar :preset="false">
      <DocxEditor.Toolbar.Bold />
      <DocxEditor.Toolbar.Italic />
    </DocxEditor.Toolbar>
  </LocaleProvider>
</template>

More control

See @docx-editor.dev/i18n for supported parts, types, and additional examples.