From 4f75b4fea589fe1b273c19613a4be58572b1afee Mon Sep 17 00:00:00 2001
From: Taylor Krusen <taylor.krusen@redocly.com>
Date: Thu, 5 Sep 2024 13:33:04 -0700
Subject: [PATCH] docs: add translate command page (#1706)

---
 docs/commands/index.md     |  1 +
 docs/commands/translate.md | 87 ++++++++++++++++++++++++++++++++++++++
 docs/sidebars.yaml         |  6 ++-
 3 files changed, 92 insertions(+), 2 deletions(-)
 create mode 100644 docs/commands/translate.md

diff --git a/docs/commands/index.md b/docs/commands/index.md
index e03d75d2..febd87be 100644
--- a/docs/commands/index.md
+++ b/docs/commands/index.md
@@ -9,6 +9,7 @@ Documentation commands:
 - [`preview-docs`](preview-docs.md) Preview API reference docs for the specified API description.
 - [`build-docs`](build-docs.md) Build API description into an HTML file.
 - [`preview`](preview.md) Start a local preview of a Redocly project with one of the product NPM packages.
+- [`translate`](translate.md) Generate translation keys for a Redocly Realm, Reef, or Revel project.
 
 API management commands:
 
diff --git a/docs/commands/translate.md b/docs/commands/translate.md
new file mode 100644
index 00000000..a63e1151
--- /dev/null
+++ b/docs/commands/translate.md
@@ -0,0 +1,87 @@
+# `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
+
+```bash
+redocly translate <locale>
+redocly translate all
+redocly translate --help
+redocly translate --version
+```
+
+## Options
+
+| Option          | Type    | Description                                                                                                                            |
+| --------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `locale`        | string  | **REQUIRED** Name of a locale folder, inside your project's `l10n` directory, to generate translations for. Use `all` for all locales. |
+| `--lint-config` | string  | Severity level for config file linting. Possible values: `warn`, `error`, `off`. Defaults to `warn`.                                   |
+| `--help`        | boolean | Show help.                                                                                                                             |
+| `--version`     | boolean | Show 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:
+
+```bash {% title="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:
+
+```bash {% title="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:
+
+```treeview {% title="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
+└── ...
+```
+
+## 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
+
+- See how to [configure localization](https://redocly.com/docs/realm/author/how-to/config-l10n) in your Redocly project.
+
+- Configure which languages users can select using the [localization option](https://redocly.com/docs/realm/config/l10n) (`l10n`) in `redocly.yaml`.
diff --git a/docs/sidebars.yaml b/docs/sidebars.yaml
index f59b342f..b8fb9a1d 100644
--- a/docs/sidebars.yaml
+++ b/docs/sidebars.yaml
@@ -12,6 +12,8 @@
           page: commands/build-docs.md
         - label: bundle
           page: commands/bundle.md
+        - label: check-config
+          page: commands/check-config.md
         - label: join
           page: commands/join.md
         - label: lint
@@ -32,8 +34,8 @@
           page: commands/split.md
         - label: stats
           page: commands/stats.md
-        - label: check-config
-          page: commands/check-config.md
+        - label: translate
+          page: commands/translate.md
     - group: Guides
       page: guides/index.md
       items: