Last updated

translate

The translate command helps you to manage multiple translations in your Redocly project (Reef, Revel, or Realm only). It creates or updates translations.yaml files, populating them with "translation keys" that map to elements in your documentation's UI.

This command serves two purposes:

  • On first run, translate creates (or populates) a file with built-in translation keys for common UI elements.
  • On future runs, translate adds custom, user-defined translation keys from your redocly.yaml or sidebars.yaml files.

Usage

redocly translate <locale>
redocly translate all
redocly translate --help
redocly translate --version

Options

OptionTypeDescription
localestringREQUIRED Name of a locale folder, inside your project's l10n directory, to generate translations for. Use all for all locales.
--lint-configstringSeverity level for config file linting. Possible values: warn, error, off. Defaults to warn.
--project-dir, -dstringPath to the project directory. The default value is . (current directory).
--helpbooleanShow help.
--versionbooleanShow version number.

Examples

The following sections show some common use cases for the translate command.

Populate translation keys for specific locale

The following command generates or updates translations for the Dutch locale:

Translate specific locale
redocly translate nl-NL

The translations are placed in the file @l10n/nl-NL/translations.yaml. If the file (or folder) doesn't exist, they're created and populated with translation keys.

Populate translation keys for all locales

Use the all keyword to generate translations for all the locale folders inside the @l10n directory:

Translate all locales
redocly translate all

This command updates the translation.yaml files for every locale with a folder in @l10n, as shown in the following example:

Project with multiple locales
your-awesome-project
├──@l10n/
│   ├──es-ES/
│   │   ├──transcriptions.yaml
│   │   └── ...
│   ├──fr/
│   │   ├──transcriptions.yaml
│   │   └── ...
│   └──nl-NL/
│       ├──transcriptions.yaml
│       └── ...
├──index.md
├──sidebars.md
├──redocly.yaml
└── ...

Populate translation keys in a specific project

Use the --project-dir option to run the translate command from a parent folder and populate translation keys inside a specific project:

redocly translate all --project-dir='museum-docs'

The following project structure represents the output of running this command from the projects folder:

Multiple projects in same folder
projects/
├──storage-docs/
├──authentication-docs/
└──museum-docs/
├──@l10n/
│   ├──es-ES/
│   │   ├──transcriptions.yaml
│   │   └── ...
│   ├──fr/
│   │   ├──transcriptions.yaml
│   │   └── ...
│   └──nl-NL/
│       ├──transcriptions.yaml
│       └── ...
├──index.md
├──sidebars.md
├──redocly.yaml
└── ...

The --project-dir option is designed to help manage multiple projects by reducing the need for traversal.

Tips for using translate

  • The command is additive; it doesn't overwrite existing translation keys.

  • Custom translation keys used in React components must be manually added to the translation.yaml file. They are not populated by the command.

  • After using the command, review a translation file to ensure new translation keys are present.

  • Automating this command can help keep translation keys updated across multiple locales.

Resources

 
Next page