GitLab CIの構成例
信頼できるGitLabパイプラインでファイルを翻訳し、マージリクエストで反映。翻訳が最新でないマージリクエストはチェックで失敗させます。
GitLabランナーでは、Lingo.dev CLIを使ってリポジトリ内のファイルを翻訳し、結果をジョブアーティファクトとして保存できます。これにより、翻訳にもアプリケーションの他の部分と同じチェックアウト、チェック、リリースのプロセスを適用できます。GitLabはパイプラインの実行とリポジトリへの反映を担い、Lingo.devは選択されたソースファイルをローカライゼーションエンジンで処理します。
これはCIの構成例であり、GitLabアカウントとのネイティブ連携ではありません。まずはデフォルトブランチでパイプラインを手動実行し、結果を確認してから、定期実行のトリガーやマージリクエストによる反映を追加してください。
ソースと認証情報を準備する #
ローカル環境でCLIクイックスタートを完了してください。.lingo/config.json、採用済みのターゲットファイル、.lingo/lock.jsonをコミットします。設定では、ソースロケール、ターゲットロケール、ファイルパターン、ローカライゼーションエンジンを選択します。その設定があるディレクトリからCLIを実行してください。
lingo push --backfill-missing --waitで不足しているターゲットファイルを作成します。その後のソースの編集には、通常のlingo push --waitを使用してください。ローカライゼーションエンジンへの指示を変更するだけでは、採用済みのファイルは書き換えられません。意図的に再生成するには、別の操作が必要です。
プロジェクトのCI/CD変数設定で、LINGO_API_KEYをマスク対象の変数として保存します。CLIが読み取るのはこの名前だけです。以前のCLIで使われていたLINGODOTDEV_API_KEY変数は無視されるため、名前を変更してください。翻訳処理の送信を許可する、信頼できるブランチや環境でのみ使用できるように制限してください。保護された変数は、保護されていないブランチやマージリクエストでは利用できない場合があります。信頼できないコードに変数を公開せず、使用が許可されたブランチを使ってください。
APIキーは、翻訳の実行を認可するためのものです。リポジトリへの書き込み権限を持つGitLabの認証情報が必要になるのは、コミットによる反映を追加するときだけです。
この例では、CLIのバージョンを1.21.0に固定しています。lingo checkによる翻訳ファイルのチェックは、CLI 1.20.0以降で利用できます。プロジェクトの依存関係とLockfileでバージョンを管理するには、継続的インテグレーションのセットアップガイドに従ってください。
まずアーティファクトを生成するパイプラインを実行する #
この.gitlab-ci.ymlの例では、locales/en.jsonがソースとして設定され、既存のスペイン語ファイルlocales/es.jsonだけが翻訳先になっていることを前提としています。翻訳先が複数ある場合は、翻訳先ファイルごとにtest -sとJSONのチェックを1回ずつ実行し、locales/es.jsonを指定しているほかのコマンドには、すべての翻訳先パスを列挙してください。Lockfileにはソースが翻訳済みとして記録されるため、以降のプッシュではそのソースがスキップされます。成果物やコミットに含めなかった翻訳先は、古いまま残ります。この例では、既定のブランチで手動起動するパイプラインを使用します。
stages:
- translate
translate_catalog:
stage: translate
image: node:22
rules:
- if: '$CI_PIPELINE_SOURCE == "web" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
script:
# Replace 1.21.0 with the current CLI version.
- npx -y @lingo.dev/cli@1.21.0 push --wait
- test -s locales/es.json
- node -e 'JSON.parse(require("node:fs").readFileSync("locales/es.json", "utf8"))'
- git diff -- locales/es.json .lingo/lock.json
artifacts:
paths:
- locales/es.json
- .lingo/lock.json--waitを指定すると、ジョブは実行の完了を待って、翻訳済みファイルをチェックアウト内に書き込みます。指定しない場合、lingo pushは実行を送信するだけで終了するため、後続のステップには検査やコミットの対象となる新しいファイルがありません。
ランナーからレジストリにアクセスできることを確認し、後続の手順に必要なツールを用意してください。たとえば、別の最小構成イメージを使う場合は、差分の確認やコミットの前にGitのインストールが必要になることがあります。
コミット済みの.lingo/config.jsonで、組織とエンジンのIDを確認します。ソースを1か所編集し、パイプラインを起動してください。ログで、報告された実行状態と変更されたターゲットエントリを確認します。アーティファクトをダウンロードし、翻訳をそのリビジョンのソースと比較してから、アプリケーションに読み込んでください。ファイルの存在確認とJSONのチェックだけでは、内容が最新か、意味が正しいかまでは確認できません。
--waitは処理が完了した出力をダウンロードしますが、人によるレビューが設定されていると、担当者の対応待ちになることがあります。レビュー待機や別の取得ジョブを使用する前に、CIの実行状態を保持する手順を追加してください。送信後に、対象のポインターと元のプロジェクトルートの絶対パスをエクスポートします。アクセスを制限したジョブアーティファクトに、.lingo-ci/run.json、.lingo-ci/project-root.txt、.lingo/config.json、locales/en.json、ターゲット、Lockfileを含めてください。artifactsの設定でwhen: alwaysを指定し、レビューに十分な保持期間を確保します。後続の検証が失敗した場合もエクスポートが実行されるようにし、元の失敗は隠さないでください。
レビューを完了してから、取得用ランナー上の同じ絶対パスのルートに、記録したリビジョンとファイルの状態を復元します。復元するポインターは対象のものだけにし、認証は別途行い、結果を取得する前にlingo pull --dry-runを使用してください。ランナーで元のパスを再現できない場合は、両方のジョブで永続的な認可済みランナーを使用してください。~/.lingo全体をアーカイブしてはいけません。送信が成功したことや、古いターゲットファイルが存在することだけでは、公開用の新しいファイルは得られません。
翻訳をマージリクエストにコミットする #
このジョブは、マージリクエスト内のソースの変更を翻訳し、結果を同じブランチにコミットします。初回の不足分の補完がコミット済みで、エンジンの「人によるレビュー」が無効になっており、1つのジョブで翻訳を完了できることを前提としています。
GitLab 18.4以降では、設定 → CI/CD → ジョブトークンの権限 → リポジトリへのGitプッシュリクエストを許可を有効にしてください。このジョブはGitLabの組み込みトークンを使用するため、開始する人にはソースブランチへのプッシュ権限が必要です。GitLabのジョブトークン設定を参照してください。
LINGO_API_KEYはマスクと保護を有効にしたままにしてください。同じプロジェクト内の信頼できるソースブランチとターゲットブランチを使用し、両方を保護します。そのうえで、プロジェクトのCI/CD設定でマージリクエストパイプラインによる保護された変数とランナーへのアクセスを許可を有効にしてください。パイプラインを開始する人には、ターゲットブランチへのプッシュ権限またはマージ権限も必要です。これらは保護された変数に関するGitLabの要件です。
最初の例と同じソースパスとターゲットパスを使用してください。このジョブをtranslateステージに追加します。
translate_merge_request:
stage: translate
image: node:22
resource_group: lingo-mr-$CI_MERGE_REQUEST_IID
rules:
- if: >-
$CI_PIPELINE_SOURCE == "merge_request_event" &&
$CI_MERGE_REQUEST_EVENT_TYPE == "detached" &&
$CI_MERGE_REQUEST_SOURCE_PROJECT_ID == $CI_MERGE_REQUEST_TARGET_PROJECT_ID
script:
# Replace 1.21.0 with the current CLI version.
- npx -y @lingo.dev/cli@1.21.0 push --wait
- test -s locales/es.json
- node -e 'JSON.parse(require("node:fs").readFileSync("locales/es.json", "utf8"))'
- git add -- locales/es.json .lingo/lock.json
- if git diff --cached --quiet; then exit 0; fi
- git config user.name "Localization bot"
- git config user.email "localization@example.com"
- git commit -m "Update translations"
- git push "$CI_REPOSITORY_URL" "HEAD:refs/heads/$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"resource_groupは、マージリクエストごとに翻訳ジョブを一度に1つずつ実行します。このジョブがコミットするのは、スペイン語のターゲットと翻訳用のLockfileだけです。翻訳中にブランチが変更されると、Gitはプッシュを拒否します。その場合は、更新後のブランチでパイプラインを実行してください。
CI_REPOSITORY_URLがジョブトークンの認証情報を提供します。このトークンによるプッシュでは別のパイプラインが起動しないため、コミットの手順より前にアプリケーションのリソースチェックを追加してください。マージリクエストで翻訳の差分をレビューし、残りのチェックを実行してからマージします。
このプッシュではパイプラインが起動しないため、マージリクエストの最新コミットには対応するパイプラインがありません。プロジェクトでパイプラインの成功を必須とする設定が有効になっていると、GitLabがマージをブロックする場合があります。その場合は、マージリクエストのパイプラインタブでパイプラインを実行を選択してください。ジョブはプッシュ対象がないことを確認し、コミットせずに終了します。このパイプラインによって、最新コミットにステータスが付与されます。
既定のブランチから翻訳のマージリクエストを作成する#
このジョブは、既定のブランチに反映された変更をその都度翻訳し、結果を含むマージリクエストを作成します。GitLabのプッシュオプションを使うと、同じgit pushでマージリクエストを作成できるため、API呼び出しや追加ツールは不要です。前述のジョブと同様、初回の一括翻訳がコミット済みで、人によるレビューが無効になっていることを前提としています。
デベロッパーのロールとwrite_repositoryスコープを持つプロジェクトアクセストークンを作成します。GITLAB_PUSH_TOKENという名前で、マスクと保護を有効にしたCI/CD変数として保存してください。GitLab.comでプロジェクトアクセストークンを利用するには、有料プランが必要です。CI_JOB_TOKENを使ったプッシュではGitLabがパイプラインを起動しないため、ここでは使用しません。プッシュ先のURLにはCI_SERVER_FQDNを使用します。これにより、セルフマネージドインスタンスが標準以外のポートを使用していても、そのポートが保持されます。CI_SERVER_FQDNにはGitLab 16.10以降が必要です。それより古いセルフマネージドインスタンスでは、代わりに${CI_SERVER_HOST}:${CI_SERVER_PORT}を使用してください。
このジョブをtranslateステージに追加します。
translate_default_branch:
stage: translate
image: node:22
resource_group: lingo-translations
rules:
- if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
script:
- git fetch --quiet "$CI_REPOSITORY_URL" "$CI_DEFAULT_BRANCH"
- if [ "$(git rev-parse FETCH_HEAD)" != "$CI_COMMIT_SHA" ]; then exit 0; fi
# Replace 1.21.0 with the current CLI version.
- npx -y @lingo.dev/cli@1.21.0 push --wait
- test -s locales/es.json
- node -e 'JSON.parse(require("node:fs").readFileSync("locales/es.json", "utf8"))'
- git add -- locales/es.json .lingo/lock.json
- if git diff --cached --quiet; then exit 0; fi
- git config user.name "Localization bot"
- git config user.email "localization@example.com"
- git commit -m "Update translations"
- >-
git push --force
-o ci.skip
-o merge_request.create
-o merge_request.target="$CI_DEFAULT_BRANCH"
-o merge_request.title="Update translations"
"https://oauth2:${GITLAB_PUSH_TOKEN}@${CI_SERVER_FQDN}/${CI_PROJECT_PATH}.git"
"HEAD:refs/heads/lingo/translations"lingo push --waitは、翻訳先のいずれかでチェックに失敗するとゼロ以外のステータスで終了するため、ジョブはコミット前に停止します。変更がない場合は「プッシュするものがありません」と表示され、ステージング済みの差分も空になるため、ジョブはコミットせずに終了します。
最初の2行は、既定のブランチがジョブの実行対象コミットより先に進んでいる場合に、ジョブを停止します。resource_groupはジョブを一度に1つずつ実行しますが、GitLabの既定のunordered処理モードでは、待機中のジョブが開始される順序は決まっていません。このチェックがないと、古いジョブが最後に実行され、強制プッシュによって新しい翻訳を古い翻訳で上書きするおそれがあります。最新コミットに対応するジョブがそのコミットを翻訳し、すでに古くなったコミットについては何も送信しません。
このジョブがループすることはありません。既定のブランチへのプッシュ時にのみ実行され、書き込み先はlingo/translationsに限られます。GitLabのドキュメントによると、-o ci.skipが影響するのはブランチパイプラインだけで、マージリクエストパイプラインには影響しません。また、マージリクエストパイプラインは、マージリクエストの作成時、またはソースブランチに新しいコミットが追加されたときに実行されます。そのため、以下のチェックは翻訳のマージリクエストで実行されるはずです。初回実行時に確認してください。そのマージリクエストをマージするとジョブがもう一度起動しますが、プッシュ対象は見つかりません。
実行のたびに、実行対象となった既定のブランチのコミットからlingo/translationsを再構築し、強制プッシュします。そのため、開いているマージリクエストには最新の翻訳差分が表示されます。そのブランチで手動編集した内容は次回の実行で置き換えられるため、手動編集はマージ後に行ってください。マージリクエストがマージされるまでは、既定のブランチに以前の.lingo/lock.jsonが残るため、次回の実行でも同じソース変更が再送信されます。後続のコミットで、そのマージリクエストが翻訳したソース変更がすべて取り消されると、次回の実行ではプッシュ対象が見つからず、古い翻訳を含むマージリクエストが開いたまま残ります。その場合は、マージせずに閉じてください。
翻訳が最新でないマージリクエストをチェックで失敗させる#
lingo checkは、設定された各ソースを.lingo/lock.jsonと比較し、すべての翻訳先ファイルが存在することを確認します。最後の翻訳後にソースが変更された場合、ソースに対応するLockfileのエントリがない場合、翻訳先ファイルがない場合、またはfilesパターンに一致するソースファイルがない場合は、ステータス1で終了します。APIキーもCI/CD変数も不要で、書き込みも行わないため、フォークからのマージリクエストでも実行できます。DO_NOT_TRACK=1で無効にできるCLIのテレメトリを除き、ネットワーク通信は行いません。ただし、npxの例では、チェックの実行前にnpmからCLIをダウンロードします。このチェックは、以前のCLIの--frozenによるチェックに代わるものです。
チェックの対象はキーではなくファイルです。翻訳先を手動で編集してもチェックは通過します。また、Reactの.jsoncカタログを除き、既存の翻訳先でキーが欠落していても報告されません。.lingo/lock.jsonがないとソースの変更を検出できないため、変更されたソースや一度もプッシュされていないソースがあってもチェックは失敗せず、その旨が標準エラー出力に表示されます。lingo pushが書き込むLockfileをコミットしてください。
stagesリストにcheckを追加してから、構成に合ったジョブを追加します。開発者がlingo push --waitを実行し、その結果をソースの変更と一緒にコミットする場合は、すべてのマージリクエストをチェックしてください。
check_translations:
stage: check
image: node:22
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
script:
# lingo check needs CLI 1.20.0 or newer.
- npx -y @lingo.dev/cli@1.21.0 check既定のブランチのジョブを使う場合は、そのジョブが作成する翻訳のマージリクエストだけをチェックしてください。機能開発のマージリクエストでは、翻訳前にソースが変更されるためです。
check_translations:
stage: check
image: node:22
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_SOURCE_BRANCH_NAME == "lingo/translations"'
script:
# lingo check needs CLI 1.20.0 or newer.
- npx -y @lingo.dev/cli@1.21.0 checkこのチェックは、翻訳をソースの変更と一緒にコミットする構成に適しています。
| 翻訳の実行場所 | すべてのマージリクエストでチェックするか |
|---|---|
開発者がlingo push --waitを実行し、結果をコミットしてからマージリクエストを作成する | はい。ソースが変更されたのに翻訳されていないマージリクエストは、チェックに失敗します。 |
| マージリクエストのジョブがソースブランチにコミットする | いいえ。翻訳前のコミットがチェックされ、ジョブによるプッシュでは新しいパイプラインが起動しないためです。 |
| 既定のブランチのジョブが翻訳のマージリクエストを作成する | 上記の2つ目のジョブを使い、lingo/translationsだけをチェックします。機能開発のマージリクエストでは、設計上、翻訳前にソースが変更されます。 |
ソースのハッシュは、バイト単位の違いも厳密に反映します。lingo pushを実行したチェックアウトと継続的インテグレーションでのチェックアウトで、改行コードを統一してください。たとえば、.gitattributesで* text=auto eol=lfを指定します。
定期実行の動作を予測可能にする #
自動ジョブの対象は、意図した信頼できるブランチとソースパスに絞り込んでください。マージリクエストのトリガーを使用する場合は、ソースプロジェクトとターゲットブランチも制限します。適切なブランチルールまたはCIをスキップするポリシーに、差分が空の場合の終了処理を組み合わせ、生成されたコミットによって翻訳が繰り返し送信されないようにしてください。
モノレポでは、対象の設定があるパッケージに移動し、そのパッケージからの相対パスを保って出力と状態を保持してください。独立したパッケージでは、それぞれ異なるローカライゼーションエンジンやロケールを使用できます。Lockfileはパッケージごとに分けて管理してください。ネットワークアクセス、ランナーのツール、変数、リポジトリのポリシーが対応していれば、セルフマネージドのGitLabでも同じランナー方式を使用できます。
通常の差分翻訳では、ソースが変わらない限り、手動で編集したターゲットキーを保持できます。ソースが変わると、そのキーが再生成される場合があります。不足しているファイルの補完と強制再生成では、対象範囲が異なります。ファイルパターンを指定しない場合、--forceは設定済みのすべてのソースロケールとターゲットロケールを対象とし、採用済みの翻訳を置き換える可能性があります。強制実行する前に、パターンを明示して見積もりを確認してください。送信コマンドを変更する際は、プッシュを参照してください。
パイプラインの復旧と運用終了に対応する #
エラーを手がかりに、次に必要な対応を判断してください。パッケージのインストールの修復、認可された変数の指定、レビューの完了、マージの競合の解消、原因を修正してからの失敗したターゲット処理の再試行などが考えられます。成功したアーティファクトは保持しつつ、一部しか完了していないリリースは、未完了だと分かる状態にしておいてください。
新たなパイプラインの起動を止めるには、トリガーを無効にしてください。ランナーをキャンセルする際は、送信済みの翻訳の状態を別途確認します。この構成の運用を終了する際は、不要になったAPIとリポジトリの認証情報を削除してください。