Last updated

Configure localization

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

To configure localization, complete the following tasks:

  1. Set up folders and config
  2. Add translated content
  3. Create translations.yaml files

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 and config

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

To set up localization folders:

  1. Create a @l10n folder in the root directory of your project.

  2. 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 translations for Spanish, French, and Japanese languages:

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

Configure localization in redocly.yaml

Define the display labels for the languages you support.

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

  1. In redocly.yaml add l10n key to the the top level of the file.
    l10n:
  2. 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.
    l10n:
  locales:
    - code: en
    - code: zh-Hans
    - code: zh-Hant
    - code: fr 
    - code: ja
    - code: es-419
    - code: es-ES
  3. For each code, add a name option, and as its value, add the label you want to appear in the language picker.
    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)
  4. Add the defaultlocale option with the value that is the code of the default language in your project.
    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

Markdown, OpenAPI, and GraphQL pages are translated as a whole. To translate these types of files into another language, create a new file in the desired language subfolder inside the @l10n folder.

The relative path from the language subfolder to the translated file should 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 path/to/my/markdown.md, the file translated to Spanish must be /@l10n/es-ES/path/to/my/markdown.md.

Create translation.yaml files

To support other languages in your project, a translations.yaml file must be present in each language subfolder.

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 user interface (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. You can translate these labels by assigning their keys a new value in the translations.yaml file.

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

theme.userMenu.login: acceso

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 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:

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

To translate navbar and footer items, specify the groupTranslationKey and labelTranslationKey properties alongside the group and label properties in your redocly.yaml file, then define those translations in the corresponding translations.yaml files. After, the label and group properties are optional and serve as defaults to be used when no translations are available.

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: theme.navbar.home
      page: /
    - group: Products
      groupTranslationKey: theme.navbar.products.label
      items:
        - page: /redocly-museum/
          label: Redocly Museum API
          labelTranslationKey: theme.navbar.products.redocly-museum
footer:
  items:
    - groupTranslationKey: theme.footer.legal.label
      items:
        - label: Terms of Use
          labelTranslationKey: theme.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

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

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.

The following is an example sidebars.yaml file with the groupTranslationKey and labelTranslationKey properties alongside the group and label 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 navbar and footer 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

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:

  1. Add a translations.yaml file to the root of your project.
  2. Copy and paste the l10n translation keys to the file.
  3. Add your customized values for the translation keys.
  4. 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.

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 curent lang
  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

  • Learn about internationalization in Internationalization (l10n)
  • Configure how languages are displayed in the language picker in the l10n configuration reference documentation.
 
Next page