lingo push

ソースの変更を送信し、不足している翻訳先ファイルを補完したり、選択した翻訳を明示的に更新したりします。

最初のファイルのセットアップが済んだら、通常のソース編集にはlingo push --waitを使います。CLIはソースのバイト列をベースラインと比較し、変更分の処理をリクエストして、完了した翻訳先ファイルをダウンロードします。バイト単位で同一のソースはスキップされます。

ほかのモードには、それぞれ異なる用途があります。毎回のプッシュを全体の翻訳と捉えるのではなく、何を変更したいかに応じて選んでください。

処理を選ぶ #

実行方法動作
有効なベースラインがない状態での通常のプッシュソースのバイト列を保存します。初回の翻訳は自動ではリクエストしません。
ベースラインがある状態での通常のプッシュソースの変更分を順次翻訳します。
lingo push 'locales/en.json'通常の前回ソースとの差分比較を行わず、対象範囲に基づいて処理を計画します。既存の翻訳先を採用することもできます。
lingo push --backfill-missing設定済みの各ソースについて、不足している翻訳先ファイルを作成します。
--forceを指定した範囲限定のプッシュ既存の翻訳先のコンテキストを保持せず、選択した個別ファイル形式の翻訳先を再生成します。
--keyを指定したプッシュ既存の翻訳先から、安定したキーを持つ単位を選択します。変更のない値を再利用できるかどうかは、形式によって異なります。

バックフィルでは、既存の通常の翻訳先ファイルに、新規キーや変更されたキーは追加されません。ベースライン以降にソースの変更がある場合は警告が表示されます。既存の言語を最新に保つには、バックフィルの前に通常のプッシュでこれらの更新を完了してください。設定済みロケールの一部だけを対象とするドキュメントでも、既存のソースベースラインは保持されます。そのため、後で通常のプッシュを行えば、残りのロケールに対する未処理の編集も処理できます。共有のXCStringsカタログでは、ロケールごとの処理計画を使います。位置引数のパターンは、任意のファイルを対象に加えるものではなく、設定済みの対象を絞り込むものです。

オプション #

オプション効果
位置引数のパターン設定済みのファイルを選択します。シェルのワイルドカードは引用符で囲んでください。
--force, -fファイル全体の翻訳を置き換えます。明示的なファイルパターン、またはバックフィルと組み合わせて使います。
--backfill-missing不足している翻訳先ファイルを初期作成します。
--key <pattern>安定した単位を選択します。繰り返し指定できます。
--yes, -y強制実行の確認を省略します。
--wait, -w送信後すぐに終了せず、完了を待ってダウンロードします。
--estimate翻訳やジョブの作成を行わずに、処理を計画して費用を見積もります。
--with <stage>今回のプッシュに限り、ステージを実行します。複数回指定できます。
--without <stage>今回のプッシュに限り、ステージをスキップします。複数回指定できます。
--review-*, --content-length今回のプッシュに限り、ステージの設定を調整します。

真偽値フラグは既定で無効です。翻訳先は設定から取得され、プッシュにロケール指定フラグはありません。ファイル全体の強制実行では確認を求められますが、確認省略、キー範囲、または見積もりを指定すると、この確認は省略されます。位置引数のパターンがない場合、--forceは設定済みのすべてのソースファイルと翻訳先ロケールを選択します。広範囲を置き換える前に、ファイルパターンを明示的に指定し、--estimateで対象範囲を確認してください。個別ファイル形式では、強制実行によって現在の翻訳先のコンテキストが消去されるため、手動で編集した翻訳先も置き換えられることがあります。XCStringsカタログとCSVテーブルでは、共有ソースファイルに埋め込まれた翻訳を引き続き再利用できます。

選択したキーを更新する #

保存済みの翻訳指針は変わったもののソーステキストは変わっていない場合や、特定の一部だけを再翻訳したい場合は、キー単位の更新を使います。

sh
lingo push 'locales/en.json' --key 'checkout.title' --key 'checkout.submit' --wait

キーは、ドットや角括弧で表すパスです。オブジェクトを選択すると、その配下のすべての文字列が対象になります。auth.loginにはauth.login.titleが含まれますが、auth.login_urlは含まれません。*は、パスを構成する一つの要素全体を表します。以前のCLIで使われていたauth/loginのようなスラッシュ形式も使用できます。JSON、JSONC、TypeScript、PHPでは、ソースが変わっていなくても、選択した文字列を再生成します。YAMLとルートキー形式のYAMLでもキーを選択できますが、ソースが保存済みのベースラインと一致する場合は、現在の翻訳先の値が再利用されることがあります。YAMLの表現を修正するには、翻訳先を直接編集してください。翻訳指針の変更後に広範囲を再生成するには、承認済みの翻訳先を保存し、--keyを付けずにファイル全体を対象とする--forceを使ってください。

翻訳先ロケールが存在しない場合や、安定したキーを持たない形式の場合は、メッセージを表示してスキップします。それ以外の形式では、エラーでプッシュを停止します。不足している翻訳先は別途初期作成してください。--keyに--forceを追加しても、キー範囲に基づく処理計画は変わらず、YAMLの再利用も抑止されません。

キー範囲を限定したプッシュでは、push --waitで結果を取得しても、後からpullで取得しても、ソース全体のベースラインは変わりません。そのため、未処理の通常のソース編集は、次の通常のプッシュで引き続き処理されます。形式ごとの対応状況とキーの構文については、スコープを参照してください。

広範囲を置き換える前に見積もる #

sh
lingo push 'locales/en.json' --force --estimate

見積もりでは、翻訳やジョブの作成を行わず、実際の差分に基づいて処理を計画します。その計画に必要なファイルのうち、サーバーにないものはアップロードされます。そのため、オフラインの試行ではなく、サービスへの呼び出しが発生します。保存済みのプル用ポインターや完了済みのベースラインは置き換えません。初回のプッシュはソースの保存のみを行うため、見積もりでは対象がないことを示し、lingo push --estimate --backfill-missingを案内します。

出力には、予定費用、生成する翻訳と再利用する翻訳、出力トークン、ロケール別の行が表示されます。後続の修正が必要になった場合の費用と、ご自身のAIプロバイダーから請求される費用は別の行に表示され、予定費用の合計には含まれません。続く警告には、見積もりに含まれない項目が示されます。~が付いた金額は概算です。これらは計画を示すものであり、実測の使用量や正式な見積もりではありません。プッシュが大きすぎて見積もれない場合は、サーバーから返された理由を表示して失敗します。ファイルパターンを指定して、一部を見積もってください。

1回のプッシュに限ってステージを変更する #

bash
lingo push 'locales/en.json' --force --wait --with human-review --review-level strict --review-timeout 12 --without pre-edit

ステージフラグを使うと、今回のプッシュに限ってエンジンのパイプラインを変更できます。エンジンを編集したり作り直したりせずに、設定を試せます。フラグで指定しない設定には、人によるレビューのプールも含め、すべてエンジンの設定が使われます。

--withと--withoutには、pre-edit、rephrase、human-review、post-edit、content-length、back-translationのいずれかを指定できます。翻訳は常に実行されます。--withoutは、スキップしたステージに依存するステージもスキップします。--without human-reviewを指定すると、AI評価とポストエディットがスキップされます。

設定値
--review-leveleverythingはすべてのユニットをレビュー担当者に送ります。strict、medium、laxは、AI評価で該当する重大度の問題が指摘されたユニットだけを送ります。
--review-pool <name>レビューには、エンジンのプールの代わりにこのプールを使用します。
--review-languages <locales>--review-poolプールでレビューするロケールをカンマ区切りで指定します。既定ではすべてのロケールが対象です。
--review-timeout <hours>レビュー担当者に割り当てる時間数。
--content-length <rule>source、match:<percent>、max:<columns>のいずれか。

設定はステージの動作を調整するもので、ステージ自体を有効にはしません。そのため、対象のステージが実行されない場合、プッシュは失敗します。--with human-reviewまたは--with content-lengthを追加してください。レビュープールのないエンジンで--with human-reviewを指定するには、--review-poolが必要です。ご利用のプランで利用できないステージを指定すると、そのステージはスキップされず、プッシュが失敗します。このプッシュも、通常のプッシュと同じように結果を書き込みます。変更のないユニットも再翻訳するには--forceまたは--keyを、事前にその設定での料金を確認するには--estimateを追加してください。再試行時には、同じステージフラグを再度指定する必要があります。

新しい言語を追加する場合は、まず既存の翻訳先に対する通常のソース更新を完了してください。その後、targetLocalesにその言語を追加し、lingo push --backfill-missing --estimateを確認してから、ソースのリビジョンを変えずにバックフィルをリクエストします。言語を追加するでは、この手順からアプリケーションの確認までを説明しています。ロケールを削除すると、以降の選択対象から外れますが、ファイルは削除されません。共有のXCStringsカタログでは、ロケールの完全削除を使わないでください。

結果の取得と復旧 #

待機を指定しない場合は、pullで出力を取得するまで、チェックアウトと、そのマシンに保存されたポインターを保持してください。別のプッシュによって、そのポインターが置き換えられることがあります。待機を指定した場合は、失敗または一部失敗となった結果と、実際にダウンロードされたファイルを確認してください。未完了の翻訳先がすべて人によるレビュー待ちになると、待機は終了します。レビュー担当者の作業が終わったら、プルを実行してください。待機による直接取得では、プルのように最新のローカル編集との比較は行われないため、取得中は翻訳先を編集しないでください。

失敗した処理を再試行するには、原因を修正し、失敗した実行の復旧手順に従ってください。状態を保持したまま適切なプッシュを再実行し、表示されたジョブIDを確認してから、得られた出力を確認します。前回のプッシュの結果をまだ取得しておらず、リクエストも変わっていない場合は、重複して作成せずに、そのリクエストを再利用します。実行中のジョブには再接続し、完了済みのジョブからは結果を取得し、失敗したジョブは新しいジョブに置き換えます。