feat: add docs for the new logto translate cli

docs/docs/references/applications/README.mdx

@@ -1,3 +1,7 @@
+---
+sidebar_position: 4
+---
+
 import Availability from '@components/Availability';
 
 import ApplicationTypesIntro from '../../fragments/_application_types_intro.mdx';

docs/docs/references/connectors/README.mdx

@@ -1,3 +1,7 @@
+---
+sidebar_position: 5
+---
+
 import ConnectorPlatformIntro from './fragments/_connector_platform_intro.mdx';
 import ConnectorStorageIntro from './fragments/_connector_storage_intro.mdx';
 import ConnectorTypeIntro from './fragments/_connector_type_intro.mdx';

docs/docs/references/core/README.mdx

@@ -1,3 +1,7 @@
+---
+sidebar_position: 6
+---
+
 import BasicTokenRequirements from './fragments/_basic-token-requirements.mdx';
 import BearerAuth from './fragments/_bearer-auth.md';
 

docs/docs/references/core/_category_.json

@@ -1,4 +1,4 @@
 {
-  "collapsible": false,
+  "collapsible": true,
   "collapsed": false
 }

docs/docs/references/resources/README.md

@@ -1,3 +1,7 @@
+---
+sidebar_position: 7
+---
+
 import APIResourceSchema from './fragments/\_api_resource_schema.mdx';
 
 # 📁 API Resource

docs/docs/references/sdk-convention/README.md

@@ -1,3 +1,7 @@
+---
+sidebar_position: 8
+---
+
 # 📃 SDK convention
 
 This section demonstrates SDK functionalities provided by Logto and the convention between various languages and platforms.

docs/docs/references/translate-cli/README.mdx

@@ -0,0 +1,72 @@
+---
+sidebar_position: 10
+---
+
+# 🤖 I18n translation with CLI
+
+Logto translate CLI is a powerful tool designed for developers contributing to Logto's i18n efforts. With this CLI, you can focus on writing content in English, and then easily translate it into all supported languages.
+
+For regular Logto users seeking custom translations without contributing to the project, please refer to our [localization guide](/docs/recipes/customize-sie/localized-language/).
+
+:::info
+Started from v1.20.0, the translation command is removed from the `@logto/cli`, and maintained as a standalone `@logto/translation` package in the logto monorepo. Accordingly, the way of execution is slightly different.
+:::
+
+## Migrate from `@logto/cli`
+
+Here's a comparison of the old and new CLI execution methods:
+
+Old method (before v1.20.0):
+
+```bash
+pnpm cli translate <command> [options]
+```
+
+New method:
+
+```bash
+pnpm translate <command> [options]
+```
+
+## Sync keys
+
+Let's say we made some changes to the translation keys in the `en` folder of the `phrases` package. We want to sync these changes to the `pt-BR` folder. Run the command below to sync translation keys and file structure:
+
+```bash
+pnpm translate sync-keys --target pt-BR
+```
+
+This command will read all translation keys from the source language folder (`en` by default) and sync them to the target language folder (`pt-BR` in this example).
+
+- If the target language folder doesn't exist, it will be created automatically;
+- If the target language folder already exists, it will be updated with new keys and removed with obsolete keys.
+
+For each translation key:
+
+- If a key is missing in the target, it will be added with a comment to indicate that the phrase is untranslated (marked with `/** UNTRANSLATED */`);
+- If a key is missing in the baseline, it will be removed from the target;
+- If a key exists in both the baseline and the target, the value of the target will be used.
+
+To sync keys for all languages in the `phrases` package, run the command below:
+
+```bash
+pnpm translate sync-keys --target all
+```
+
+Thus we can focusing on updating the translation keys in the source language folder, and the translation keys in other languages will be updated automatically.
+
+:::info
+This command executes for `phrases` package by default. You can specify the package name by `--package` option. For example, use `--package phrases-ui` to sync keys for the `phrases-ui` package.
+:::
+
+After syncing keys, we can translate the keys using ChatGPT API.
+
+## Translate keys using ChatGPT
+
+Run the command below to translate keys using ChatGPT:
+
+```bash
+pnpm translate sync
+```
+
+This command will translate all untranslated keys (marked with `// UNTRANSLATED`) across all languages in the `phrases` and `phrases-ui` packages. Note an environment variable `OPENAI_API_KEY` is required to run this command.

docs/docs/references/users/README.md

@@ -1,3 +1,7 @@
+---
+sidebar_position: 9
+---
+
 # 👨‍👩‍👧‍👦 Users
 
 The _users_ are the main entities of the identity service.

docs/docs/references/using-cli/translation.mdx

@@ -4,6 +4,10 @@ sidebar_position: 5
 
 # Translation
 
+:::info
+Started from v1.20.0, the translate command is removed from the `@logto/cli`, and maintained as a standalone `@logto/translate` package in the logto monorepo. Please refer to the [translate CLI](/docs/references/translate-cli/) for more details.
+:::
+
 :::info
 These commands are for developers who want to contribute to Logto. If you just want to use Logto with custom translation, please refer to [this guide](/docs/recipes/customize-sie/localized-language/).
 :::
@@ -23,7 +27,7 @@ This command will read all translation keys from the source language folder (`en
 
 For each translation key:
 
-- If a key is missing in the target, it will be added with a comment to indicate that the phrase is untranslated (marked with `// UNTRANSLATED`);
+- If a key is missing in the target, it will be added with a comment to indicate that the phrase is untranslated (marked with `/** UNTRANSLATED */`);
 - If a key is missing in the baseline, it will be removed from the target;
 - If a key exists in both the baseline and the target, the value of the target will be used.