翻訳
プロジェクトを翻訳する方法
使い方
本番用にアプリをビルドする前に、CI パイプラインでこれを実行してください。
npx gtx-cli translate注意: このコマンドを実行するには本番用のAPIキーが必要です。プラットフォームで取得してください。
概要
gtx-cli translate コマンドは、プロジェクトを翻訳します。
プロジェクトのファイルツリーを走査し、<T> コンポーネントで囲まれたコンテンツや
useGT 関数を使用しているコンテンツを翻訳します。
さらに、dictionary ファイル（存在する場合）に含まれるコンテンツも反映します。
このコマンドは General Translation API および関連サービスを利用する主な手段です。
本番環境専用です！
このコマンドは本番ビルドを想定しており、開発環境では使用しないでください。
実行前に、本番リリースに使用するブランチに切り替えていることを確認してください。
また、環境変数に本番用の APIキー（GT_API_KEY）と Project ID（GT_PROJECT_ID）を設定することも忘れないでください。
使い方
translate コマンドの利用方法は3通りあります。方法1と2は本番環境用のAPIキーが必要です:
translate コマンドを実行する前に、セットアップウィザード（npx gtx-cli configure）の実行を推奨します。プロジェクトの設定を支援します。
プロジェクトの設定内容によっては、translate コマンドの動作が変わる場合があります。
方法 1: プジェクトの JSON ファイルを翻訳する
next-intl、react-i18next、next-i18next などの他の i18n ライブラリを使用している場合、この方法でプロジェクトの JSON ファイルを翻訳できます。
翻訳は自動的にコードベースに保存されます。
CLI ツールでプロジェクトの JSON ファイルを翻訳するには、gt.config.json の files プロパティに json を含めるように設定してください。
詳細は CLI 設定ドキュメント を参照してください。
npx gtx-cli translateCLI ツールは package.json を読み取り、使用中の i18n ライブラリを自動的に検出します。また、そのライブラリの構文に準拠して JSON を翻訳します。
方法 2: GT プロジェクトを翻訳する
プロジェクトで gt-next または gt-react を使用している場合、この方法でプロジェクト用の翻訳を生成できます。
npx gtx-cli translateデフォルトでは、翻訳は GT CDN に保存されます。
ただし、翻訳をコードベースに保存したい場合は、gt.config.json ファイル内の files オブジェクトに gt プロパティを追加してください。
gt-next と gt-react は、General Translation のパブリック CDN の利用に加えて、ローカル配信にも対応しています。
レイテンシの低減、パフォーマンス向上、バンドルサイズ削減のため、CDN の使用を推奨します。
詳しくは、CLI 設定ドキュメントをご覧ください。
方法 3: プロジェクトの <T> コンポーネントと dictionary ファイルを検証する
この方法は、プロジェクトの <T> コンポーネントと dictionary ファイルの検証に役立ちます。
これにより、プロジェクトが正しく設定され、翻訳が有効かつ正確であることを確認できます。
--dry-run フラグが指定されている場合、翻訳は生成されません。
npx gtx-cli translate --dry-runフラグ
| Parameter | Description | Type | Optional | Default |
|---|---|---|---|---|
--api-key | 本番用のAPIキーを指定します | string | true | |
--project-id | プロジェクトIDを指定します | string | true | |
--version-id | バージョンIDを指定します（デフォルトはコンテンツのハッシュ） | string | true | |
--config <path> | GTの設定ファイルへのパスを指定します | string | true | "gt.config.json" |
--tsconfig, --jsconfig <path> | TSまたはJSの設定ファイルへのパスを指定します | string | true | |
--src <paths> | ソースファイルにマッチするglobパターンをスペース区切りで指定します。ルートディレクトリからの相対パスで指定してください。 | [string] | true | [ 'src/**/*.{js,jsx,ts,tsx}', 'app/**/*.{js,jsx,ts,tsx}', 'pages/**/*.{js,jsx,ts,tsx}', 'components/**/*.{js,jsx,ts,tsx}', ] |
--dictionary <path> | dictionaryファイルへのパスを指定します | string | true | |
--inline | dictionaryに加えてインラインの<T>タグを含めます | boolean | true | true |
--timeout | 翻訳リクエストのタイムアウト（秒） | number | true | 600 |
--new, --locales <locales> | プロジェクトを翻訳する対象ロケール | [string] | true | |
--default-locale <locale> | プロジェクトのソースlocale | string | true | en |
--ignore-errors | エラーを無視し、有効なコンテンツのみ強制的に翻訳します | flag | true | false |
--dry-run | コマンドをドライランで実行します | flag | true | false |
--force | プロジェクトの再翻訳を強制します | flag | true | false |
--force-download | プロジェクトのすべての翻訳を強制的にダウンロードします | flag | true | false |
これらのパラメータはすべて任意です。
gt.config.json ファイルにAPIキーを追加しないでください！
代わりに環境変数として設定してください。CLIは、設定されている場合、自動的に GT_API_KEY を読み取ります。
主なパラメータは次のとおりです:
| Parameter | Description |
|---|---|
--dry-run | このフラグを指定すると、CLIはプロジェクトを解析・検証しますが、GT APIとは通信しません。コードベースの検証に有用です。 |
--api-key | --dry-run を使用しない場合は、本番用のAPIキーを指定する必要があります。 |
--project-id | 同様に、--dry-run を使用しない場合は、プロジェクトIDを指定する必要があります。 |
--new, --locales <locales> | プロジェクトを翻訳する対象ロケール。gt.config.json で指定された対応ロケールに追加されます。 |
--force | プロジェクトの再翻訳を強制し、既存の翻訳をすべて上書きします。 |
--force-download | すべての翻訳のダウンロードを強制し、ローカルで加えた翻訳の変更を上書きします。 |
設定ファイル
CLI ツールを初めて実行すると、プロジェクトのルートに gt.config.json ファイルの作成を試みます。
このファイルには、コンテンツの翻訳に使用されるプロジェクトに関するメタデータが含まれています。
gt.config.json ファイルの詳細はこちらをご覧ください。
重要なポイント
コンテンツソース
translate コマンドは、プロジェクト内の翻訳対象コンテンツを再帰的に検索します。
既定では、次のディレクトリを検索します:
./src./app./pages./components
--src フラグを使用するか、gt.config.json ファイルの src プロパティを変更して、検索対象の別ディレクトリを指定できます。
翻訳の上書き
デフォルトでは、ソースコンテンツに変更がない限り、CLI はローカルで加えた翻訳の変更を上書きしません。
すでに翻訳済みのプロジェクトコンテンツを再翻訳したい場合は、--force フラグを使用できます。
--force を使用すると、既存のすべての翻訳が上書きされ、ローカルで加えた変更は保持されません。
最新のプロジェクト翻訳をすでに取得済みで、再度ダウンロードしたい場合は、--force-download フラグを使用できます。
--force-download を使用すると、ローカルで加えた翻訳への変更は上書きされ、最新の翻訳が取得されます。コンテンツの再翻訳は行われません。
dictionary ファイル
translate コマンドは、プロジェクト内の dictionary ファイルを自動的に検出します。
既定では、以下のディレクトリで dictionary.[json|ts|js] というファイルを検索します:
./src./
--dictionary フラグを使用するか、gt.config.json ファイルの dictionary プロパティを変更して、別の dictionary ファイルを指定できます。
このガイドはどうでしたか？