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 folders and config
- Add translated content
- 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:
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 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:
- In
redocly.yaml
addl10n
key to the the top level of the file.l10n:
- Add a
locales
option and inside it a map ofcode
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
- For each
code
, add aname
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)
- 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
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 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> ); }
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!
Navbar and footer labels
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
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.
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:
- 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.
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.