\n\n# @docx-editor.dev/i18n\n\nTranslate [docx-editor.dev](https://docx-editor.dev) controls with locale strings, types, and runtime helpers. The package provides ten languages and falls back to English for missing translations.\n\n## Quick start\n\nInstall the locale package:\n\n```bash\nnpm install @docx-editor.dev/i18n\n```\n\nPass a locale to the editor. This example requires the React adapter and its engine peer:\n\n```tsx\nimport { DocxEditor } from '@docx-editor.dev/react';\nimport { de } from '@docx-editor.dev/i18n';\n\n;\n```\n\nTo share a locale across editors and custom controls, use `LocaleProvider`:\n\n```tsx\nimport { DocxEditor, LocaleProvider } from '@docx-editor.dev/react';\nimport { de } from '@docx-editor.dev/i18n';\n\n\n \n;\n```\n\nChrome you write yourself reads the same catalog through `useTranslation()`.\n\nMix a community locale with custom overrides:\n\n```ts\nimport { de } from '@docx-editor.dev/i18n';\n\nconst myLocale = {\n ...de,\n formattingBar: { ...de.formattingBar, bold: 'Fettdruck' },\n};\n```\n\nKeys set to `null` in any locale fall back to English.\n\n## Available locales\n\n| Code | Export | Language |\n| ------- | ------ | ------------------- |\n| `en` | `en` | English (source) |\n| `de` | `de` | German |\n| `fr` | `fr` | French |\n| `he` | `he` | Hebrew |\n| `hi` | `hi` | Hindi |\n| `id` | `id` | Indonesian |\n| `pl` | `pl` | Polish |\n| `pt-BR` | `ptBR` | Portuguese (Brazil) |\n| `tr` | `tr` | Turkish |\n| `zh-CN` | `zhCN` | Simplified Chinese |\n\nBCP-47 codes (`pt-BR`, `zh-CN`) use camelCase JS identifiers (`ptBR`, `zhCN`). For runtime lookup by tag:\n\n```tsx\nimport { locales } from '@docx-editor.dev/i18n';\n\n\n \n;\n```\n\nImporting `locales` includes every locale in your bundle. Import individual locales to reduce the bundle size.\n\n## Per-locale subpaths\n\nIf 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:\n\n```ts\n// Static import: include only this locale's strings.\nimport pl from '@docx-editor.dev/i18n/pl';\n```\n\nFor on-demand loading, use a dynamic import instead:\n\n```ts\nconst pl = (await import('@docx-editor.dev/i18n/pl')).default;\n```\n\nSubpaths ship for every locale: `/en`, `/de`, `/fr`, `/he`, `/hi`, `/id`, `/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.\n\n## Types\n\nImport types to describe locale data and translation functions:\n\n```ts\nimport type {\n LocaleStrings, // shape of `en`, the full source of truth\n PartialLocaleStrings, // shape of a community partial (null falls back)\n Translations, // alias for PartialLocaleStrings\n TranslationKey, // 'formattingBar.bold' | 'navigation.find.counter' | ...\n LocaleCode, // 'en' | 'de' | 'pt-BR' | ...\n TFunction, // signature of the `t()` callback\n} from '@docx-editor.dev/i18n';\n```\n\n## Outside the React adapter\n\nBuild a typed `t()` outside the adapter packages:\n\n```ts\nimport { createT, deepMerge, en, de, type LocaleStrings } from '@docx-editor.dev/i18n';\n\nconst merged = deepMerge(en, de) as LocaleStrings;\nconst t = createT(merged, 'de');\nt('formattingBar.bold'); // 'Fett'\nt('navigation.find.total', { total: 15 }); // ICU plurals\n```\n\n`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](https://github.com/eigenpal/docx-editor/blob/main/docs/i18n.md).\n\n## Contributing\n\nTo contribute, see [CONTRIBUTING.md](https://github.com/eigenpal/docx-editor/blob/main/CONTRIBUTING.md) for setup, tests, and the one-time CLA signature.\n\n## Commercial support\n\nFor commercial support or custom features, [email the support team](mailto:docx-editor@eigenpal.com).\n","readmeFilename":"README.md"}
![\"DOCX](\"https://raw.githubusercontent.com/eigenpal/docx-editor/main/.github/assets/header.png\")
\n \n![\"npm](\"https://img.shields.io/npm/v/@docx-editor.dev/i18n.svg?style=flat-square&color=3B5BDB\")
\n ![\"npm](\"https://img.shields.io/npm/dm/@docx-editor.dev/i18n.svg?style=flat-square&color=3B5BDB\")
\n ![\"license\"](\"https://img.shields.io/badge/license-Apache_2.0-blue.svg?style=flat-square&color=3B5BDB\"){kind=icon}
\n ![\"Demo\"](\"https://img.shields.io/badge/Live_Demo-3B5BDB?style=flat-square&logo=vercel&logoColor=white\"){kind=icon}
![\"Documentation\"](\"https://img.shields.io/badge/Docs-3B5BDB?style=flat-square&logo=readthedocs&logoColor=white\"){kind=icon}