Configure localization

You can make your project accessible to users who speak other languages by configuring localization.

To configure localization, complete the following tasks:

Set up folder structure for localization
Configure locales
Add translated content
Localize the user interface (UI)

Before you begin

Make sure you have the following:

a redocly.yaml file in the root directory of your project
translated content

Set up localization folder structure

The first step is to set up the localization folder structure.

To set up localization folders:

Create a @l10n folder in the root directory of your project.
In the @l10n folder add a subfolder for each non-default language you want to support. Redocly recommends using IETF language tags to name the subfolders. For example, the following structure includes language subfolders for Spanish, Spanish for the Latin America and Caribbean region, French, Japanese, and Chinese written in traditional and in simplified script:
```
your-awesome-project
├── @l10n
│   ├── es-ES
│   ├── es-419
│   ├── fr
│   ├── ja
│   ├── zh-Hans
│   └── zh-Hant
├── index.md
└── redocly.yaml
```

Configure locales in `redocly.yaml`

Define the display labels for the languages you support.

To add the l10n configuration to the redocly.yaml file:

In redocly.yaml add the l10n key to the top level of the file.
redocly.yaml
```
l10n:
```
Add a locales option and inside it a map of code options with the values that are the names of your language subfolders and the code for your project's default language.
The order of the language codes determines the order of languages in the language picker of your project.
redocly.yaml
```
l10n:
  locales:
    - code: en
    - code: zh-Hans
    - code: zh-Hant
    - code: fr 
    - code: ja
    - code: es-419
    - code: es-ES
```

For each code, add a name option, and as its value, add the label you want to appear in the language picker.

redocly.yaml

l10n:
  locales:
    - code: en
      name: English
    - code: zh-Hans
      name: Chinese (Simplified)
    - code: zh-Hant
      name: Chinese (Traditional)
    - code: fr
      name: French
    - code: ja
      name: Japanese
    - code: es-419
      name: Spanish (Latin America)
    - code: es-ES
      name: Spanish (Spain)

Add the defaultlocale option with the value that is the code of the default language in your project.

redocly.yaml

l10n:
  defaultLocale: en
  locales:
    - code: en
      name: English
    - code: zh-Hans
      name: Chinese (Simplified)
    - code: zh-Hant
      name: Chinese (Traditional)
    - code: fr
      name: French
    - code: ja
      name: Japanese
    - code: es-419
      name: Spanish (Latin America)
    - code: es-ES
      name: Spanish (Spain)

Add translated content files

To add a translated Markdown file or API description file to your project, place the files in their respective language subfolders inside the @l10n folder.

The relative path from the language subfolder to the translated file must be the same as the relative path from the root of the project to the file in the default language. For example, if you originally had a file with path ./index.md, the file translated to Spanish must be located in ./@l10n/es-ES/index.md.

    your-awesome-project
    ├── @l10n
    │   ├── es-ES
    │   │   ├── images
    │   │   ├── index.md
    │   │   └── openapi.yaml   
    │   ├── es-419
    │   │   ├── images
    │   │   ├── index.md
    │   │   └── openapi.yaml
    │   ├── fr
    │   │   ├── images
    │   │   ├── index.md
    │   │   └── openapi.yaml
    │   ├── ja
    │   │   ├── images
    │   │   ├── index.md
    │   │   └── openapi.yaml
    │   ├── zh-Hans
    │   │   ├── images
    │   │   ├── index.md
    │   │   └── openapi.yaml
    │   └── zh-Hant
    │       ├── images
    │       ├── index.md
    │       └── openapi.yaml
    ├── images
    ├── index.md
    ├── openapi.yaml
    └── redocly.yaml

Localize UI elements

The translations.yaml file contains key-value pairs for a specific language. These pairs are used to translate different types of content, including the following:

Navbar, footer, and sidebar labels: Define and translate project labels by updating the sidebars.yaml or redocly.yaml files with the translation keys and including a translations.yaml file in each language subfolder with the language specific key-value pairs.
Base UI component labels: Translate base UI component labels by including a translations.yaml file in each language subfolder with the language specific key-value pairs.
Content on React pages: Define and translate content on React pages by creating the translation keys on the React page and including a translations.yaml file in each language subfolder with the language specific key-value pairs.

Base UI component labels include predefined keys; however, you must create keys for all other types of content.

Base UI components

Each label from the components that come bundled with the project has a predefined translation key assigned to it. See l10n translation keys for a comprehensive list of all predefined translation keys available.

To localize base UI components:

If you haven't already, add a translations.yaml file to each of your language subfolders.
Copy and paste the l10n translation keys into each translations.yaml file in the language subfolders.
Add the translated values for the translation keys.
Commit your changes.

For example, to translate the login button text to Spanish, use the following key in your translations.yaml file in the es-ES subfolder:

translations.yaml

theme.userMenu.login: acceso

To translate labels in the navbar and the footer:

If you haven't already, add a translations.yaml file to each of your language subfolders.

In the root directory's redocly.yamlfile, find the navbar and footer options and to each group add the groupTranslationKey option, as in the following example:

redocly.yaml

navbar:
  items:
    - label: Home
      page: /
    - group: Products
      groupTranslationKey: navbar.products.label
      items:
        - page: /redocly-museum/
          label: Redocly Museum API
footer:
  items:
    - groupTranslationKey: footer.legal.label
      items:
        - label: Terms of Use
          labelTranslationKey: footer.legal.termsOfUse
          href: '/terms-of-use/'

For more information, see: navbar config and footer config topics.

Add the labelTranslationKey option to each label, as in the following example:

redocly.yaml

navbar:
  items:
    - label: Home
      labelTranslationKey: navbar.home
      page: /
    - group: Products
      groupTranslationKey: navbar.products.label
      items:
        - page: /redocly-museum/
          label: Redocly Museum API
          labelTranslationKey: navbar.products.redocly-museum
footer:
  items:
    - groupTranslationKey: footer.legal.label
      items:
        - label: Terms of Use
          labelTranslationKey: footer.legal.termsOfUse
          href: '/terms-of-use/'

Copy the values for the groupTranslationKey and labelTranslationKey options to each locale's translations.yaml file in your project, as in the following example:
translations.yaml
```
navbar.home:
navbar.products.label:
navbar.products.redocly-museum:
footer.legal.label:
footer.legal.termsOfUse:
```

Add the translated values, as in the following example:

translations.yaml

navbar.home: página de inicio
navbar.products.label: productos
navbar.products.redocly-museum: Redocly Museo
footer.legal.label: Legal
footer.legal.termsOfUse: Condiciones de uso

Commit your changes.

The following is an example of redocly.yaml file that includes the groupTranslationKey and labelTranslationKey properties alongside the group and label properties for navbar and footer links:

redocly.yaml

navbar:
  items:
    - label: Home
      labelTranslationKey: navbar.home
      page: /
    - group: Products
      groupTranslationKey: navbar.products.label
      items:
        - page: /redocly-museum/
          label: Redocly Museum API
          labelTranslationKey: navbar.products.redocly-museum
footer:
  items:
    - groupTranslationKey: footer.legal.label
      items:
        - label: Terms of Use
          labelTranslationKey: footer.legal.termsOfUse
          href: '/terms-of-use/'

The following example is the corresponding translations.yaml file for the Spanish language with the key-value pairs for the navbar and footer links:

translations.yaml

navbar.home: página de inicio
navbar.products.label: productos
navbar.products.redocly-museum: Redocly Museo
footer.legal.label: Legal
footer.legal.termsOfUse: Condiciones de uso

Sidebars

Adding translations to sidebars is similar to translating navbar and footer labels. You specify the groupTranslationKey, labelTranslationKey, and separatorTranslationKey properties alongside the group, label, and separator properties respectively and then define translations in corresponding translations.yaml files.

To translate labels in the sidebars:

If you haven't already, add a translations.yaml file to each of your language subfolders.

In every sidebars.yaml file in your project:

To each group, add a groupTranslationKey option.
To each label, add a labelTranslationKey option.
To each separator, add a separatorTranslationKey option. The following example is a sidebar with translation keys added to each group, label, and separator:

sidebars.yaml

- group: Getting Started
  groupTranslationKey: sidebar.gettingStarted
  items:
    - separator: My separators
      separatorTranslationKey: sidebar.gettingStarted.separator
    - group: Introduction
      groupTranslationKey: sidebar.gettingStarted.introduction
      separatorLine: true
      items:
        - page: index.md
          label: First steps
          labelTranslationKey: sidebar.gettingStarted.first-steps
- page: overview.md
  label: Installation
  labelTranslationKey: sidebar.installation

Copy the values of groupTranslationKey, labelTranslationKey, and separatorTranslationKey to each translations.yaml file in your project as in the following example:
translations.yaml
```
sidebar.gettingStarted:
sidebar.gettingStarted.separator:
sidebar.gettingStarted.introduction:
sidebar.gettingStarted.first-steps:
sidebar.installation:
```

Add the translated values, as in the following example:

translations.yaml

sidebar.gettingStarted: Commencer
sidebar.gettingStarted.separator: Mes séparateurs
sidebar.gettingStarted.introduction: Introduction
sidebar.gettingStarted.first-steps: Premiers pas
sidebar.installation: Installation

Commit your changes.

The following is an example sidebars.yaml file with the groupTranslationKey, labelTranslationKey, and separatorTranslationKey properties alongside the group, label, and separator properties for sidebar links:

sidebars.yaml

- group: Getting Started
  groupTranslationKey: sidebar.gettingStarted
  items:
    - separator: My separators
      separatorTranslationKey: sidebar.gettingStarted.separator
    - group: Introduction
      groupTranslationKey: sidebar.gettingStarted.introduction
      separatorLine: true
      items:
        - page: index.md
          label: First steps
          labelTranslationKey: sidebar.gettingStarted.first-steps
- page: overview.md
  label: Installation
  labelTranslationKey: sidebar.installation

The following example is the corresponding translations.yaml file for the French language with the key-value pairs for the sidebar links:

translations.yaml

sidebar.gettingStarted: Commencer
sidebar.gettingStarted.separator: Mes séparateurs
sidebar.gettingStarted.introduction: Introduction
sidebar.gettingStarted.first-steps: Premiers pas
sidebar.installation: Installation

React pages

You must create translations keys in the React file before you can assign it a language specific value in the translations.yaml file.

To translate content in React pages, use the useTranslate hook by importing it from @redocly/theme/core/hooks. This hook returns a translate function which accepts the following two arguments:

a translation key
a default value which is used when a translation is missing

The following is an example of a React page with a translated heading 1:

import React from 'react';

import { useTranslate } from '@redocly/theme/core/hooks';

export default function () {
  const { translate } = useTranslate();
  return (
    <div>
      <h1>{translate('react-page.heading', 'This is default fallback text!')}</h1>
    </div>
  );
}

Note

The react-page.heading is an arbitrary name. You can name your translation keys however you want.

The heading on the example React page includes the same text for all languages by default, "This is default fallback text!". To translate it to different languages, add the key react-page.heading to the respective translations.yaml files, as in the following example for a Spanish translation:

translations.yaml

react-page.heading: ¡Este es un texto traducido!

Change the built-in UI labels

Redocly projects come with a set of built-in UI labels in US English. You can configure a translations.yaml file to override these labels, accomplishing the following goals:

Adjust the UI text to better suit your project (for example, change "Login" to "Sign in").
Change the language used in the UI, without adding a language picker.

To change the built-in UI labels:

Add a translations.yaml file to the root of your project.
Copy and paste the l10n translation keys to the file.
Add your customized values for the translation keys.
Commit your changes.

The following is an example translations.yaml file that if included in the root of your project, changes the label of the login button to "Sign in":

theme.userMenu.login: Sign in

Alternatively, you can change the labels in the default UI components, by ejecting the components you want to change.

Localize partial content

To localize content re-used in partials:

Add a folder with the same name as your partials folder to each of your language subfolders.
Place the translated content in each of the partials folders.

    your-awesome-project
    ├── _partials
    ├── @l10n
    │   ├── es-ES
    │   │   ├── _partials
    │   │   ├── images
    │   │   ├── index.md
    │   │   └── openapi.yaml
    │  ... 
    ├── images
    ├── index.md
    ├── openapi.yaml
    └── redocly.yaml

Access the current locale

React pages

To access the current locale in React pages, use the useL10n hook by importing it from @redocly/theme/core/hooks.

import React from 'react';

import { useL10n } from '@redocly/theme/core/hooks';

export default function () {
  const { lang } = useL10n(); // access to current language
  return (
    <div>
      <h1>Current language: {lang} </h1>
    </div>
  );
}

Markdoc pages

To access the current locale in Markdoc pages, use the global $lang variable.

# Current language: {% $lang %}

Resources

Configure how languages are displayed in the language picker in the l10n configuration reference documentation.
Learn more about how localization works in a Redocly project in the Localization concept documentation.

Configure localization

Before you begin

Set up localization folder structure

Configure locales in `redocly.yaml`

Add translated content files

Localize UI elements

Base UI components

Navbar and footer labels

Sidebars

React pages

Change the built-in UI labels

Localize partial content

Access the current locale

React pages

Markdoc pages

Resources

Was this helpful?

Configure localization

Before you begin

Set up localization folder structure

Configure locales in redocly.yaml

Add translated content files

Localize UI elements

Base UI components

Navbar and footer labels

Sidebars

React pages

Change the built-in UI labels

Localize partial content

Access the current locale

React pages

Markdoc pages

Resources

Was this helpful?

Configure locales in `redocly.yaml`