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
orredocly.yaml
files with the translation keys and including atranslations.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:
- A Redocly project with a
l10n
folder containing your translated content organized into locales. See Set up folder structure and Add translated content for more information.
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 value pair in your translations.yaml
file in the es-ES
subfolder:
userMenu.login: acceso
Navbar and footer labels
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.yaml
file, find thenavbar
andfooter
options and to eachgroup
add thegroupTranslationKey
option, as in the following example:For more information, see: navbar config and footer config topics.redocly.yamlnavbar: 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/'
- Add the
labelTranslationKey
option to eachlabel
, as in the following example:redocly.yamlnavbar: 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
andlabelTranslationKey
options to each locale'stranslations.yaml
file in your project, as in the following example:translations.yamlnavbar.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:
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:
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 agroupTranslationKey
option. - To each
label
, add alabelTranslationKey
option. - To each
separator
, add aseparatorTranslationKey
option. The following example is a sidebar with translation keys added to eachgroup
,label
, andseparator
:
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
- To each
- Copy the values of
groupTranslationKey
,labelTranslationKey
, andseparatorTranslationKey
to eachtranslations.yaml
file in your project as in the following example:translations.yamlsidebar.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:
- 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:
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> ); }
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!
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":
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:
- 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.
- In the code of the highlighted element, locate the
data-translation-key
property. The translation key is the value of thedata-translation-key
property. In some cases you might need to drill down the code nested in the selected element.
Now you can add the key to the translations.yaml
file and use it to localize or customize your project.
Resources
- Find the next steps to add localization to your project in Configure localization.
- Learn how to localize your content files in Add translated content.