# `l10n`

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.

## How localization works

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.

### Supported content types

You can include translations for the following types of content:

- **Markdown, OpenAPI, and GraphQL documents** - Content in Markdown, YAML, JSON, or SDL documents
- **Navbar, footer, and sidebar labels** - Labels for items in navigation menus
- **Base UI components** - Labels for bundled components (e.g., Login button, search placeholder)
- **Content on React pages** - Headers, tiles, and other content in React components


### Folder structure

To store translated files, your project must have a `@l10n` folder at the root, with a subfolder for each additional supported language. Files outside the `@l10n` folder should be in the default language.


```treeview
your-project/
├── @l10n/
│   ├── es-ES/
│   │   ├── index.md
│   │   └── translations.yaml
│   ├── fr-FR/
│   │   ├── index.md  
│   │   └── translations.yaml
│   └── ja/
│       ├── index.md
│       └── translations.yaml
├── index.md
├── translations.yaml
└── redocly.yaml
```

To switch between languages, target language files in the localization folders **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.

### Language subfolder naming

Language subfolder names can contain only letters, numbers, and `-` or `_` symbols. Redocly recommends using [IETF language tags](https://www.rfc-editor.org/rfc/rfc5646.html) like `en` or `en-US`.

Common language tags consist of:

- **Language code**: Two-letter lowercase codes from [ISO 639-1](https://www.loc.gov/standards/iso639-2/php/English_list.php): `en`, `es`, `fr`, `ja`
- **Script subtag**: Four-letter script code from [ISO-15924](https://www.unicode.org/iso15924/codelists.html): `Hans`, `Hant`
- **Region subtag**: Two-letter uppercase country codes from [ISO 3166-1](https://www.iso.org/obp/ui/#search): `US`, `ES`, `FR`, `JP`


Use as few tags as necessary to differentiate between localization languages.

### Translation files

A `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.

## Options

| Option | Type | Description |
|  --- | --- | --- |
| defaultLocale | string | **REQUIRED**
Name of the default locale (the language of the files outside of the `@l10n` folder). |
| locales | [Locale object](#locale-object) | List of all locales, including the default locale |


### Locale object

| Option | Type | Description |
|  --- | --- | --- |
| code | string | Language code. Must match the name of the language subfolder inside the `@l10n` folder or the `defaultLocale` code.
The format of the code is `lang-COUNTRY` or `lang`, where `lang` is the [language code](https://en.wikipedia.org/wiki/ISO_639-1) and `COUNTRY` is the country code.
For example, `en-US` for English (United States) and `fr-FR` for French (France), or `en` for English.
More specific fallback locales are supported, for example `de-AT` falls back to `de`; |
| name | string | Language name that is displayed in the language picker. |


## Examples

### Complete localization setup

The following example shows a complete localization configuration for a project supporting multiple languages:

First, set up your folder structure:


```treeview
your-project/
├── @l10n/
│   ├── es-ES/
│   │   ├── index.md
│   │   ├── api-docs/
│   │   │   └── museum-api.yaml
│   │   └── translations.yaml
│   ├── fr-FR/
│   │   ├── index.md
│   │   ├── api-docs/
│   │   │   └── museum-api.yaml
│   │   └── translations.yaml
│   └── ja/
│       ├── index.md
│       ├── api-docs/
│       │   └── museum-api.yaml
│       └── translations.yaml
├── index.md
├── api-docs/
│   └── museum-api.yaml
├── translations.yaml
└── redocly.yaml
```

Then configure your locales in `redocly.yaml`:


```yaml redocly.yaml
l10n:
  defaultLocale: en
  locales:
    - code: en
      name: English
    - code: es-ES
      name: Spanish (Spain)
    - code: fr-FR
      name: French (France)
    - code: ja
      name: Japanese

navbar:
  items:
    - label: Home
      labelTranslationKey: nav.home
      page: /
    - label: API Documentation
      labelTranslationKey: nav.api.docs
      page: /api-docs/

footer:
  items:
    - label: Support
      labelTranslationKey: footer.support
      href: /support
```

### Basic localization configuration

For a minimal setup with just language switching:


```yaml redocly.yaml
l10n:
  defaultLocale: en
  locales:
    - code: en
      name: English
    - code: es
      name: Spanish
    - code: fr
      name: French
```

### Supported default translations

Redocly provides default translations for the following languages:

- `en` - English (United States)
- `ar` - Arabic
- `hi` - Hindi
- `de` - German
- `es` - Spanish
- `fr` - French
- `it` - Italian
- `ja` - Japanese
- `ko` - Korean
- `pl` - Polish
- `pt` - Portuguese (Portugal)
- `pt-BR` - Portuguese (Brazil)
- `ru` - Russian
- `uk` - Ukrainian
- `zh` - Chinese (Simplified)


## Resources

- **[Localize UI labels](/docs/realm/content/localization/localize-labels)** - Configure translation keys for navigation and UI components to support multiple languages
- **[Translation keys reference](/docs/realm/content/localization/translation-keys)** - Complete list of predefined translation keys for base UI components and interface elements
- **[Localize content](/docs/realm/content/localization/localize-content)** - Translate your Markdown and API documentation files for comprehensive international support