{
  "name": "localization",
  "title": "Localization",
  "description": "Discover how to localize eurodata-ui with minimal effort.",
  "docs": "https://test-apps.eurodata.de/a/eurodata-ui/docs/localization/",
  "sections": [
    {
      "heading": "Localization",
      "markdown": "eurodata-ui components localize themselves based on the [`lang`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang) and [`dir`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir) attributes on the `<html>` element. To render the library in German, set `lang=\"de\"` and load the German translation:\n\n```html\n<html lang=\"de\">\n  <head>\n    <script type=\"module\" src=\"/path/to/eurodata-ui/dist/translations/de.js\"></script>\n  </head>\n\n  <body>\n    ...\n  </body>\n</html>\n```\n\nA mutation observer watches the `lang` attribute, so changing it at runtime re-renders every localized component with the new locale.\n\nThis mechanism only localizes eurodata-ui's own component internals. For application content, use a full i18n framework such as [i18next](https://www.i18next.com/)."
    },
    {
      "heading": "Available Translations",
      "markdown": "eurodata-ui ships translations for the most common locales. English (US) is the default and the ultimate fallback, so you do not need to import it.\n\nEvery language is complete except Hindi (`hi`) and Kazakh (`kk`): their date input segment placeholders (year, month, day, half-year and quarter) still show the English pattern letters. In Persian, Hebrew, Japanese and Chinese the year, month and day placeholders also keep the Latin pattern letters (`yyyy`, `mm`, `dd`), as MUI does. Where a word is the same in a language as in English, such as \"Zoom\" or \"Document\" in French, the translation keeps it.\n\nLoad any other translation by its language code:\n\n```js\nimport '@eurodata/eurodata-ui/dist/translations/de.js';\n```\n\nTranslations can be registered at any time — before or after the `lang` attribute changes. Once registered, localized components update automatically.\n\n```js\n// Switch to German at runtime\ndocument.documentElement.lang = 'de';\nawait import('@eurodata/eurodata-ui/dist/translations/de.js');\n```\n\n### Translation Resolution\n\nWhen `<html lang=\"...\">` carries a region tag (e.g. `de-CH` for Swiss German), the localizer resolves the locale in this order:\n\n1.  `de-CH`\n2.  `de`\n3.  `en` (built-in fallback)\n\nEnglish is used as a fallback to avoid rendering blanks or throwing errors when a locale or term is missing."
    },
    {
      "heading": "Multiple Locales Per Page",
      "markdown": "Override the locale on a single component by setting `lang` and/or `dir` on the element itself:\n\n```html\n<html lang=\"de\">\n  ...\n\n  <body>\n    <ed-button><!-- Deutsch --></ed-button>\n    <ed-button lang=\"ru\"><!-- Russisch --></ed-button>\n  </body>\n</html>\n```\n\nFor performance reasons the override must be on the component, not an ancestor. The example below does **not** switch the button to Russian:\n\n```html\n<html lang=\"de\">\n  ...\n\n  <body>\n    <div lang=\"ru\">\n      <ed-button><!-- still in German --></ed-button>\n    </div>\n  </body>\n</html>\n```\n\nThis limitation exists because there is no efficient way to determine an element's effective locale by walking the DOM tree."
    },
    {
      "heading": "Creating Your Own Translations",
      "markdown": "If you need a locale eurodata-ui doesn't ship, or you want to override built-in strings, copy `src/translations/en.ts` and translate the terms. Register the result the same way as a built-in translation. The example below adds a German translation in TypeScript — plain JavaScript works the same way.\n\n```ts\nimport { registerTranslation } from '@eurodata/eurodata-ui';\nimport type { Translation } from '@eurodata/eurodata-ui/dist/utilities/localize.js';\n\nconst translation: Translation = {\n  $code: 'de',\n  $name: 'Deutsch',\n  $dir: 'ltr',\n\n  term1: '...',\n  term2: '...',\n  ...\n};\n\nregisterTranslation(translation);\n\nexport default translation;\n```\n\nCompile the file and load it like a built-in translation:\n\n```html\n<html lang=\"de\">\n  <head>\n    <script type=\"module\" src=\"/path/to/de.js\"></script>\n  </head>\n\n  <body>\n    ...\n  </body>\n</html>\n```\n\nTo create a regional variant, spread an existing translation and override the differing terms — `src/translations/de-ch.ts` shows the pattern for Swiss German.\n\nIf your translation isn't applying, make sure `registerTranslation` is imported from the same module as the rest of your eurodata-ui code. A duplicate module won't share the registry."
    }
  ]
}