CIで翻訳を自動化する
特定のソースリビジョンを起点に、ファイルの検査とアプリケーションのチェックまで。翻訳を、繰り返し実行できるリリース工程に組み込みます。
リリースパイプラインは、ソースリビジョンを利用者が使える形につなげる仕組みです。翻訳でも、このつながりを保つ必要があります。ジョブには、変更されたソースを特定し、対応する翻訳先ファイルを取得し、次のステップで採用の可否を判断できるだけの根拠を残す役割があります。
対応が難しいケースは、最初のリクエストが成功した後に起こります。レビュー担当者がまだ編集を続けている、ランナーが突然停止する、以前の翻訳が終わる前に原文の新しいリビジョンが届く、といったケースです。このガイドでは、古いファイルを公開したり、承認済みの修正をむやみに上書きしたりすることなく、こうした状況に対応できるCIプロセスを構築していきます。プロバイダー別のYAML設定は、GitHub Actions、GitLab、Bitbucket、Buildkiteのレシピに記載されています。
リリースのどの段階に翻訳を組み込むかを決める #
リポジトリのワークフローに合う場合は、マネージドのGitHub Appを使用します。デフォルトブランチに変更が加わると、翻訳用のプルリクエストが作成されます。プルリクエストの処理を有効にした場合は、そのプルリクエストのブランチに書き込まれます。実行の承認は翻訳作業を許可するもので、コンテンツのレビューとマージはその後に行います。
CLIランナーを使う場合は、送信、取得、反映をパイプライン側で担います。リリースプロセスに合った出力先を選んでください。
| 出力先 | 判断できること |
|---|---|
| 成果物のみ | リポジトリやリリースに変更を加える前に、別のジョブまたは担当者が出力を検査します。 |
| 翻訳用ブランチとプルリクエスト | 翻訳の変更をデフォルトブランチに取り込む前に、個別にレビューします。 |
| ソースのプルリクエストのブランチ | ソースと翻訳を一つの変更としてまとめてレビューします。 |
| デフォルトブランチへの直接コミット | ブランチポリシーで明示的に許可されている場合は、翻訳専用のプルリクエストを作らずに反映します。 |
リポジトリに書き込む場合は、同じ翻訳状態への書き込みを担う実行元を一つに絞ります。そうしないと、異なるソースリビジョンで動作する二つのランナーが、ファイルとLockfileのコミットで競合するおそれがあります。また、生成されたコミットが翻訳を繰り返し起動しないよう、ブランチ、パス、または生成コミットに関するルールも必要です。
ランナーが引き継ぐ基準状態を整える #
繰り返し実行を有効にする前に、ローカルでソースファイルを一つ選んで一つの言語に翻訳し、アプリケーションのリソースチェックを実行します。設定、採用済みの翻訳先ファイル、.lingo/lock.jsonをまとめてコミットしてください。クリーンなチェックアウトで、同じソースの選択と翻訳先の配置を再現できる状態にします。
プロバイダー別の例では、バージョンを@lingo.dev/cli@1.21.0に固定しています。ワークフローを設定する際は、これを最新のCLIリリースに置き換えてください。CLIをプロジェクトの依存関係とともに管理するには、npm install --save-dev --save-exact @lingo.dev/cli@1.21.0でインストールし、package.jsonとpackage-lock.jsonをコミットします。その後、npm ciとnpx --no-install lingoを使って、Lockfileに記録されたバージョンを実行します。
.lingo/config.jsonでは、ロケール、ファイルパターン、ローカライゼーションエンジンを選択します。セットアップ時に、組織とローカライゼーションエンジンへのアクセスを確保してください。ジョブでプロジェクトの初期化やリンクが必要な場合は、無人実行中に入力待ちにならないよう、初期化とリンクのリファレンスに記載された明示的なオプションを使用します。
モノレポでは、目的の設定があるパッケージに移動してからCLIを実行します。位置引数のパターンは、その設定で選択されるソースを絞り込むものであり、別のパッケージの設定を選ぶものではありません。独立した設定を持つパッケージごとに、状態と成果物のパスをひとまとまりで管理してください。
ランナーのシークレット管理機能を使ってLINGO_API_KEYを渡します。対話形式のログインは不要です。ブランチ上のスクリプトを書き換えることでキーが漏えいする可能性があるため、認証情報を使うジョブは信頼できるコードからのみ実行してください。信頼できないジョブを成功させるために制限を外すのではなく、保護変数とフォークに関する制限に従って、ジョブの実行場所を決めます。
目的に合った種類の作業を送信する #
何もない状態から初めて翻訳する場合は、不足している翻訳先ファイルの作成をリクエストします。既存のプロジェクトでは、まず既存の翻訳先に対する通常のソース更新を完了させ、その結果を取得して検査します。その後、ソースリビジョンを固定したまま、不足しているロケールを追加してバックフィルを行います。次のコマンドを実行する前に、言語を追加するの手順に従ってください。
lingo push --backfill-missing --wait確立した基準状態からソースが変更された場合:
lingo push --wait最初の通常のプッシュでは、翻訳を行わず、ソースの状態だけが記録される場合があります。バックフィルで不足ファイルを作成するタスクを指定し、それ以降の通常のプッシュでは、ソースの変更に基づいて作業が決まります。範囲を限定したプッシュやバックフィルのプッシュで、既存の翻訳先ファイル内の不足キーをあらゆる場合に修復できるわけではありません。
--waitは実行の完了を待ち、完了した出力をダウンロードします。指定しない場合、プッシュは送信後に終了します。レビュー待ちや別ジョブでの取得には、CIの実行状態を保持する手順が必要です。ランナーが終了する前に、ホームディレクトリ内にある所定の機密情報を含まないポインター、元のプロジェクトルートの絶対パス、および対応するソース、設定、翻訳先、Lockfileの状態を保持します。同じルートに復元し、別途認証してから、lingo pull --dry-run、続いてlingo pullを使用してください。ランナーでそのパスを再現できない場合は、必要なアクセス権を持つ永続的なチェックアウトを代わりに使用します。認証情報や~/.lingo全体をアーカイブしてはいけません。
終了ステータスと、報告された翻訳先ごとの結果を保持します。現在のCLIは、失敗が報告された翻訳先があると失敗終了しますが、人によるレビューの判断を待ったままになる実行もあります。新しいバージョンが待機中でも、古いファイルは残っている場合があります。反映ジョブでの公開を許可する前に、レビューを完了し、結果を取得してください。
コマンドの正確な動作は、プッシュとプルを参照してください。--yesは強制再生成の確認を省略するものであり、人によるレビューを承認したり、保留中のすべての操作を完了させたりするものではありません。
CLIはCI環境では更新チェックを省略します。必要に応じて、LINGO_DISABLE_UPDATE_CHECK=1とLINGO_TELEMETRY_DISABLED=1で明示的に制御できます。翻訳の通信を無効にする必要はありません。
次のステップで使えるファイルが揃っていることを確かめる #
変更されるはずの項目を、ソースリビジョンと照合します。チェックアウトに古い翻訳先ファイルがすでに含まれている場合、ファイルが存在するだけでは十分な根拠になりません。同じ操作でダウンロードした出力とロック状態を保持し、失敗したロケールや待機中のロケールは、未完了であることが分かる状態にしておきます。
次に、リソースの特性に合ったチェックを行います。
- Reactの抽出では、
lingo extract --check、lingo check、プロジェクトのTypeScriptチェック、実際のアプリケーションビルドを実行します。それぞれ、結果の異なる部分を検査します。 - ネイティブリソースでは、プラットフォームのリソース生成またはコンパイルを実行します。
- 静的コンテンツでは、翻訳済みドキュメントを解析し、リンク、変数、保持された構文を検査します。
- 翻訳が最新でない場合にマージリクエストを失敗させるには、
lingo checkを実行します。APIキーは不要です。
lingo checkはファイル単位で動作します。設定された各ロケールについて、ソースの変更と翻訳先ファイルの欠落を報告します。既存のAndroid、Apple、ARB、Markdocファイル内で欠落しているキーを報告するものではありません。
採用した受け入れプロセスの中で、翻訳の意味も確認します。ビルドはリソースの形式不備を検出できても、重要な条件の意味が変わった文をそのまま通してしまうことがあります。チェックとレビューに通ったら、意図した出力パスだけをコミットまたは公開してください。変更がない場合はそのまま終了できるようにし、必須チェックで失敗した場合はジョブを失敗させます。無条件のコミットで失敗を覆い隠してはいけません。
代わりの作業を作成する前に、記録済みの作業を再開する #
ジョブが中断したら、実行の識別情報と翻訳先ごとの結果を復元します。翻訳が完了している場合は、別のリクエストを送信する前に、その出力をプルしてください。待機中にローカルの翻訳先ファイルが変更された場合は、採用済みの編集内容を確認できる状態でプルの競合を解消します。強制的に上書きすると、ワークフローで守るべき修正そのものを失うおそれがあります。
原因の調査中はLockfileを保持してください。削除すると次回実行時のソースの基準状態が変わり、限定的な復旧のはずが別の作業になる可能性があります。差分を確認し、未完了の範囲だけを再試行します。この判断については、中断したローカライゼーション実行を復旧するで詳しく説明しています。
ジョブの定期実行を設定する前に、成功するケースに加えて、人によるレビュー待ちと取得の中断もそれぞれ一度試してください。リリースのステップでは、たまたま存在するファイルを受け入れるのではなく、最後に採用された状態を保持し、未完了のロケールを特定できるようにします。