Last updated

Localize UI labels using translation keys

Redocly projects include user interface (UI) elements with text labels. These labels can either be the default generated labels or configured labels added by users when defining elements such as the sidebars or the footer.

To localize UI labels, first you need to add keys to the user-defined UI elements, then copy them to a translations.yaml file and add the translations to each key. A translations.yaml file contains translation keys and localized labels for a specific language. These key-value 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.

Before you begin

Make sure you have the following:

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:

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

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

translations.yaml
userMenu.login: acceso

To translate labels in the navbar and the footer:

  1. If you haven't already, add a translations.yaml file to each of your language subfolders.
  2. 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.
  3. 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/'
    
  4. 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:
    
  5. 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
    
  6. 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

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:

  1. If you haven't already, add a translations.yaml file to each of your language subfolders.
  2. 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
    
  3. 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:
    
  4. 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
    
  5. 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:

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

userMenu.login: Sign in

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

Find translation keys using your browser

Your browser's developer tools can help you identify which translation keys to use. These tools allow you to inspect HTML elements and see which translation keys are applied.

To find translation keys using browser developer tools:

  1. Right-click the page element that you want to find the translation key for and click Inspect element. The browser opens developer tools with the element highlighted in the Elements tab.
  2. In the code of the highlighted element, locate the data-translation-key property. The translation key is the value of the data-translation-key property. In some cases you might need to drill down the code nested in the selected element. A screenshot of development tools Elements tab with the location of data-translation-key highlighted

Now you can add the key to the translations.yaml file and use it to localize or customize your project.

Resources