From 0eaf9506a60d7d04c7f2cc8d7721e8ae248be4e7 Mon Sep 17 00:00:00 2001 From: Charles Zhao Date: Thu, 15 Aug 2024 19:41:39 +0800 Subject: [PATCH] feat: add docs for the new logto translate cli --- docs/docs/references/applications/README.mdx | 4 ++ docs/docs/references/connectors/README.mdx | 4 ++ docs/docs/references/core/README.mdx | 4 ++ docs/docs/references/core/_category_.json | 2 +- docs/docs/references/resources/README.md | 4 ++ docs/docs/references/sdk-convention/README.md | 4 ++ docs/docs/references/translate-cli/README.mdx | 72 +++++++++++++++++++ docs/docs/references/users/README.md | 4 ++ .../docs/references/using-cli/translation.mdx | 6 +- 9 files changed, 102 insertions(+), 2 deletions(-) create mode 100644 docs/docs/references/translate-cli/README.mdx diff --git a/docs/docs/references/applications/README.mdx b/docs/docs/references/applications/README.mdx index 1bf90860099..540ee4764e3 100644 --- a/docs/docs/references/applications/README.mdx +++ b/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'; diff --git a/docs/docs/references/connectors/README.mdx b/docs/docs/references/connectors/README.mdx index 5e3f5a2c1e4..7823cab9d23 100644 --- a/docs/docs/references/connectors/README.mdx +++ b/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'; diff --git a/docs/docs/references/core/README.mdx b/docs/docs/references/core/README.mdx index 744c571dd5b..82350a254a3 100644 --- a/docs/docs/references/core/README.mdx +++ b/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'; diff --git a/docs/docs/references/core/_category_.json b/docs/docs/references/core/_category_.json index ac08a5068ab..54510f3ea03 100644 --- a/docs/docs/references/core/_category_.json +++ b/docs/docs/references/core/_category_.json @@ -1,4 +1,4 @@ { - "collapsible": false, + "collapsible": true, "collapsed": false } diff --git a/docs/docs/references/resources/README.md b/docs/docs/references/resources/README.md index 12e06fb530f..c4819651e24 100644 --- a/docs/docs/references/resources/README.md +++ b/docs/docs/references/resources/README.md @@ -1,3 +1,7 @@ +--- +sidebar_position: 7 +--- + import APIResourceSchema from './fragments/\_api_resource_schema.mdx'; # ๐Ÿ“ API Resource diff --git a/docs/docs/references/sdk-convention/README.md b/docs/docs/references/sdk-convention/README.md index f35d6eaa76b..64d376fb241 100644 --- a/docs/docs/references/sdk-convention/README.md +++ b/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. diff --git a/docs/docs/references/translate-cli/README.mdx b/docs/docs/references/translate-cli/README.mdx new file mode 100644 index 00000000000..aa8a1f59b28 --- /dev/null +++ b/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 [options] +``` + +New method: + +```bash +pnpm translate [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. diff --git a/docs/docs/references/users/README.md b/docs/docs/references/users/README.md index 45e2953954a..15a028873f3 100644 --- a/docs/docs/references/users/README.md +++ b/docs/docs/references/users/README.md @@ -1,3 +1,7 @@ +--- +sidebar_position: 9 +--- + # ๐Ÿ‘จโ€๐Ÿ‘ฉโ€๐Ÿ‘งโ€๐Ÿ‘ฆ Users The _users_ are the main entities of the identity service. diff --git a/docs/docs/references/using-cli/translation.mdx b/docs/docs/references/using-cli/translation.mdx index 72ce91a5434..d830fc20ae9 100644 --- a/docs/docs/references/using-cli/translation.mdx +++ b/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.