{
  "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\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."
    }
  ]
}