{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"l10n","__idx":0},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["l10n"]}]},{"$$mdtype":"Tag","name":"ConfigOptionRequirements","attributes":{"products":["Revel","Realm"],"plans":["Pro","Enterprise","Enterprise+"]},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Configure localization (internationalization) for your project to support multiple languages."," ","This includes setting up the language picker, organizing translated content, and defining language-specific labels."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-localization-works","__idx":1},"children":["How localization works"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The localization feature enables you to serve your project in multiple languages."," ","You can fully localize both the content of project pages and the labels of UI components."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"supported-content-types","__idx":2},"children":["Supported content types"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can include translations for the following types of content:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Markdown, OpenAPI, and GraphQL documents"]}," - Content in Markdown, YAML, JSON, or SDL documents"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Navbar, footer, and sidebar labels"]}," - Labels for items in navigation menus"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Base UI components"]}," - Labels for bundled components (e.g., Login button, search placeholder)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Content on React pages"]}," - Headers, tiles, and other content in React components"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"folder-structure","__idx":3},"children":["Folder structure"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To store translated files, your project must have a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@l10n"]}," folder at the root, with a subfolder for each additional supported language."," ","Files outside the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@l10n"]}," folder should be in the default language."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"treeview","header":{"controls":{"copy":{}}},"source":"your-project/\n├── @l10n/\n│   ├── es-ES/\n│   │   ├── index.md\n│   │   └── translations.yaml\n│   ├── fr-FR/\n│   │   ├── index.md  \n│   │   └── translations.yaml\n│   └── ja/\n│       ├── index.md\n│       └── translations.yaml\n├── index.md\n├── translations.yaml\n└── redocly.yaml\n","lang":"treeview"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To switch between languages, target language files in the localization folders ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["must"]}," have the same structure as source language files in the root directory."," ","You can think of each language subfolder as the \"root directory\" of each localization."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"language-subfolder-naming","__idx":4},"children":["Language subfolder naming"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Language subfolder names can contain only letters, numbers, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["-"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_"]}," symbols."," ","Redocly recommends using ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://www.rfc-editor.org/rfc/rfc5646.html"},"children":["IETF language tags"]}," like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["en"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["en-US"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Common language tags consist of:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Language code"]},": Two-letter lowercase codes from ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://www.loc.gov/standards/iso639-2/php/English_list.php"},"children":["ISO 639-1"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["en"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["es"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fr"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ja"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Script subtag"]},": Four-letter script code from ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://www.unicode.org/iso15924/codelists.html"},"children":["ISO-15924"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Hans"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Hant"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Region subtag"]},": Two-letter uppercase country codes from ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://www.iso.org/obp/ui/#search"},"children":["ISO 3166-1"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["US"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ES"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FR"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["JP"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use as few tags as necessary to differentiate between localization languages."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"translation-files","__idx":5},"children":["Translation files"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["translations.yaml"]}," file in each language subfolder and the root directory stores translation keys for base UI components, navigation, and React pages."," ","When a language doesn't have a translation key defined, the project uses the key from the default language, or falls back to default values."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"options","__idx":6},"children":["Options"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Option"},"children":["Option"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["defaultLocale"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED."]}," ","Name of the default locale (the language of the files outside of the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@l10n"]}," folder)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["locales"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#locale-object"},"children":["Locale object"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["List of all locales, including the default locale"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"locale-object","__idx":7},"children":["Locale object"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Option"},"children":["Option"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["code"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Language code."," ","Must match the name of the language subfolder inside the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@l10n"]}," folder or the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["defaultLocale"]}," code."," ","The format of the code is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lang-COUNTRY"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lang"]},", where ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lang"]}," is the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://en.wikipedia.org/wiki/ISO_639-1"},"children":["language code"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COUNTRY"]}," is the country code."," ","For example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["en-US"]}," for English (United States) and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fr-FR"]}," for French (France), or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["en"]}," for English."," ","More specific fallback locales are supported, for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["de-AT"]}," falls back to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["de"]},";"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["name"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Language name that is displayed in the language picker."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"examples","__idx":8},"children":["Examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"complete-localization-setup","__idx":9},"children":["Complete localization setup"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example shows a complete localization configuration for a project supporting multiple languages:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["First, set up your folder structure:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"treeview","header":{"controls":{"copy":{}}},"source":"your-project/\n├── @l10n/\n│   ├── es-ES/\n│   │   ├── index.md\n│   │   ├── api-docs/\n│   │   │   └── museum-api.yaml\n│   │   └── translations.yaml\n│   ├── fr-FR/\n│   │   ├── index.md\n│   │   ├── api-docs/\n│   │   │   └── museum-api.yaml\n│   │   └── translations.yaml\n│   └── ja/\n│       ├── index.md\n│       ├── api-docs/\n│       │   └── museum-api.yaml\n│       └── translations.yaml\n├── index.md\n├── api-docs/\n│   └── museum-api.yaml\n├── translations.yaml\n└── redocly.yaml\n","lang":"treeview"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Then configure your locales in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly.yaml"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","data-title":"redocly.yaml","header":{"title":"redocly.yaml","controls":{"copy":{}}},"source":"l10n:\n  defaultLocale: en\n  locales:\n    - code: en\n      name: English\n    - code: es-ES\n      name: Spanish (Spain)\n    - code: fr-FR\n      name: French (France)\n    - code: ja\n      name: Japanese\n\nnavbar:\n  items:\n    - label: Home\n      labelTranslationKey: nav.home\n      page: /\n    - label: API Documentation\n      labelTranslationKey: nav.api.docs\n      page: /api-docs/\n\nfooter:\n  items:\n    - label: Support\n      labelTranslationKey: footer.support\n      href: /support\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"basic-localization-configuration","__idx":10},"children":["Basic localization configuration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For a minimal setup with just language switching:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","data-title":"redocly.yaml","header":{"title":"redocly.yaml","controls":{"copy":{}}},"source":"l10n:\n  defaultLocale: en\n  locales:\n    - code: en\n      name: English\n    - code: es\n      name: Spanish\n    - code: fr\n      name: French\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"supported-default-translations","__idx":11},"children":["Supported default translations"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Redocly provides default translations for the following languages:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["en"]}," - English (United States)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ar"]}," - Arabic"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hi"]}," - Hindi"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["de"]}," - German"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["es"]}," - Spanish"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fr"]}," - French"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["it"]}," - Italian"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ja"]}," - Japanese"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ko"]}," - Korean"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pl"]}," - Polish"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pt"]}," - Portuguese (Portugal)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pt-BR"]}," - Portuguese (Brazil)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ru"]}," - Russian"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["uk"]}," - Ukrainian"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["zh"]}," - Chinese (Simplified)"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"resources","__idx":12},"children":["Resources"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/localization/localize-labels"},"children":["Localize UI labels"]}]}," - Configure translation keys for navigation and UI components to support multiple languages"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/localization/translation-keys"},"children":["Predefined translation keys"]}]}," - Complete list of predefined translation keys for base UI components and interface elements"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/localization/localize-content"},"children":["Localize content"]}]}," - Translate your Markdown and API documentation files for comprehensive international support"]}]}]},"frontmatter":{"products":["Revel","Realm"],"plans":["Pro","Enterprise","Enterprise+"],"description":"Configure localization (internationalization) for your project to support multiple languages."},"tagList":["configOptionRequirements","table"],"title":"l10n","lastModified":"2026-10-01T23:00:57.000Z"}