プラットフォームアカウントを作成

lingo push

Max PrilutskiyCEO 兼 共同創業者読了目安 3分

ソースファイルをエンジンに送信して翻訳実行を開始します。コマンドは実行を送信すると終了します。完了まで待機して出力をディスクに書き込むには --wait を指定するか、あとで lingo pull で取得できます。

text
lingo push [patterns...] [--key <pattern>] [--force] [--backfill-missing] [--yes] [--wait] [--estimate]

デフォルトの動作 — 差分プッシュ#

引数を指定しない場合、lingo push は 差分のみモード で実行されます。

  1. 設定の files パターンに一致するすべてのソースファイルをハッシュ化する
  2. 各ハッシュをロックファイルと比較し、変更されたソースを特定する
  3. エンジンで実行を作成し、実行状態 に記録する
  4. 変更されたソースをアップロードし、実行を開始して終了する

--wait を使うと、終了せずに次を行います。

  1. 実行が完了するまで待機する
  2. 出力をディスクに書き込む
  3. 新しいソースハッシュをロックファイルにコミットする

--wait を使わない場合は、lingo pull があとで手順 5〜7 を実行します。例外は、エンジンがすでに完了済みと報告した実行です。この場合は、--wait の有無にかかわらず、すぐにダウンロードまで行います。

前回の正常な push 以降、変更されたソースがなければ、このコマンドは ✓ Nothing to push. を返して即座に終了します。サーバーとの往復も、トークン消費も発生しません。

引数とフラグ#

位置引数: patterns... — スコープ付き push#

bash
lingo push docs/en/about.md
lingo push 'docs/en/**/*.md' 'locales/en.json'

push の対象を特定のファイルに限定します（.lingo/config.json にすでに含まれているパターンに一致している必要があります）。これにより、コマンドは スコープモード に切り替わります。

  • 前回のソースとの差分比較は行われず、一致したすべてのソースが、変更の有無にかかわらずスコープ内として扱われます。
  • 一致するソースハッシュを持つターゲットがすでに存在する場合、サーバー側では noop になります。エンジンはそれらをスキップし、CLI はキャッシュ済みとして報告します。

プロジェクト全体を再ハッシュせず、更新したファイルを1つだけ確実に翻訳したいときや、--force を使って単一ページを再翻訳したいときに使います。

--key <pattern>#

bash
lingo push --key auth.login
lingo push --key auth.login --key billing.plan
lingo push --key "auth.*"

パターンが指定したキーだけを再翻訳し、既存の翻訳にマージします。それ以外のキーはすべてバイト単位でまったく同じままです。繰り返し指定でき、各パターンにつき --key を 1 つ使います。

キースコープはソース差分を見ないため、ソーステキストが一度も変わっていないキーでも再翻訳されます。これこそがこのフラグの役割です。文言変更、モデルの切り替え、用語集の更新のあとに、ファイル全体のコストをかけず、一部の文字列だけをやり直すための正式な方法です。

--force はそれ以外を何も追加せず、ファイル全体に対する確認プロンプトも出しません。

各キーで起こること#

--key で指定翻訳に存在結果
はいはい再翻訳される
はいいいえ翻訳されて追加される
いいえはい既存の翻訳を保持
いいえいいえ一切書き込まれない

最後の行こそが、キースコープと通常の push を分けるポイントです。前回のフル push 以降にソースへ追加されたキーは、ソーステキストのまま翻訳に 持ち込まれません。そのまま除外され、次回の通常の lingo push で翻訳されます。

パターンのマッチ方法#

パターン対象になるもの
auth.loginauth.login と auth.login.title — auth.login_url は含まれません
authauth とその配下のサブツリー全体 — authority は含まれません
"auth.*"auth 配下のすべて。auth.login_url を含みますが、auth は含みません
"auth*"上記に加えて authority も対象 — 境界はまったくありません

パターンは、キーに完全一致するか、.、/、-、[ のいずれかの境界で終わるプレフィックスとしてマッチするか、または glob としてマッチします。配列メンバーにはブラケット境界を通して届くため、nav.items は nav.items[0].title を対象にします。

glob は引用符で囲んでください。 先にシェルが展開してしまいます。zsh では、裸の --key auth.* は no matches found で中断されるか、あるいは auth.json のようなファイルがたまたまディレクトリにあると、そのファイル名に黙って置き換わります。カンマ区切りの値はリストではありません。--key "a,b" は何にもマッチしない 1 つのリテラルパターンです。代わりにフラグを繰り返してください。

受け付けないもの#

キースコープは、頼んでいないことまで黙って進めるのではなく、対象を報告したうえでスキップします。

  • まだ翻訳がないロケール。 マージ先がないため、そのロケール名を表示してスキップします。まず --backfill-missing で一度翻訳し、そのあとに --key を使ってください。
  • キーを省略できない形式 — ドキュメントを編集するとキーがすぐに変わってしまうドキュメント形式と、ファイルを有効な状態に保つために複数形カテゴリが必要なxcode-stringsdictです。完全な一覧はFormatsをご覧ください。これらのファイルは警告とともに除外されるため、pushではキー・バリュー形式のファイルと混在させることはできますが、--keyは付けずにpushしてください。
  • 何にもマッチしなかったスコープ は、実行結果を「すでに最新」とはせず、その旨を明示します。

位置ベースのメンバーは、スコープ指定中でもソーステキストを保持します。配列要素、Android の <string-array> 項目、<plurals> の数量項目がこれに当たります。1 つ削除すると、残りの番号が振り直されてしまうためです。

lockfile は更新されません#

キースコープ付きの実行ではファイルの一部だけを翻訳するため、lockfile 内のソースハッシュはあえてそのままにします。そのファイル内のほかの変更はまだ保留のままで、次回の通常の lingo push で取り込まれます。

--force / -f#

bash
lingo push docs/en/about.md --force

既存の翻訳を無視し、サーバー側キャッシュもバイパスして、マッチするすべてのターゲットを再翻訳します。本当にプロジェクト全体を対象にするのでなければ、位置パターンまたは --backfill-missing でスコープを絞ってください。裸の lingo push --force は設定済みのすべてのパターンを再翻訳し、それを止めるのは以下の確認だけです。

まだ一度も翻訳されていないプロジェクトでは、上書きするものがないため、--forceを使っても何も反映されません。代わりに--backfill-missingを使ってください。こちらのほうが、普段使いにも安心です。足りない部分だけを埋め、確認を求めることもありません。

デフォルトでは、--force は実行前に確認を求めます。

text
! --force will retranslate every target for pattern(s): docs/en/about.md and
  overwrite existing translations. Continue? (Yes, retranslate / Cancel)

プロンプトをスキップするには、--yes / -y を指定します（CI向け）。

ファイル全体ではなく一部の文字列だけをやり直したいなら、--key を使ってください。コストがかかるのは指定したキーだけです。

--backfill-missing#

bash
lingo push --backfill-missing

設定されたすべてのパターンについて、まだ存在しないターゲットをすべて翻訳します。設定内の全パターンを対象にしたスコープ付き push と同等ですが、存在しないファイルだけを生成します。targetLocales に新しいロケールを追加したあとや、新規プロジェクトで最初の push を行うときに使います。

--force と組み合わせると、すべてをゼロから再翻訳できます。

bash
lingo push --backfill-missing --force --yes

--yes / -y#

--force の確認プロンプトをスキップします。--force がなければ効果はなく、--key と一緒でも効果はありません。キースコープでは指定したキーにしか触れないため、そもそも確認は表示されません。

--wait / -w#

bash
lingo push --wait

実行の完了を待ち、出力を書き込み、ロックファイルを更新するところまでを、ひとつのコマンドで行えます。これを使わない場合、プッシュは実行が送信された時点ですぐに終了し、lingo pull が出力を取得します。後続の手順で翻訳をコミットするなら、CI ではこれを使うのがおすすめです。

待機中でも lingo pull は安全に使えます。翻訳はサーバー上でそのまま続行され、<C02></C02> が実行に再接続します。

--estimate#

bash
lingo push --estimate
lingo push 'docs/en/**/*.md' --estimate

この push の概算コストを表示して、翻訳は行わずに終了します。CLI は push のフルパイプライン（ハッシュ化、差分計算、ソースバイトのアップロード）を実行し、サーバーが正確な差分を算出できる状態にしたうえで、実行を開始する代わりにエンジンに料金の見積もりだけを依頼します。翻訳・書き込み・請求は一切発生せず、lockfile とターゲットファイルも変更されません。

表示される値は見積もりであり、確定額ではありません。--estimate はスコープや --key / --force / --backfill-missing と組み合わせられるため、これから実行する push の料金を正確に見積もれます。

ソースに変更がない場合、--estimate は通常の push と同じく、✓ Nothing to push. でそのまま終了します。

同じソースに対する実行がすでに進行中の場合、--estimate は途中まで開始された実行の料金を見積もるのではなく、失敗します。

text
Error: Cannot estimate: existing group lrg_a8c... is already in 'running' state. Change a source file or wait for the run to finish.

出力#

成功すると、プッシュは送信された実行を報告します。

text
Pushing source files to localization engine…
✓ Run lrg_a8c... submitted. Run lingo pull to download results when it finishes.

--wait を使うと、書き込んだ内容もあわせて報告します。

text
Pushing source files to localization engine…
✓ Run lrg_a8c...: localized 12 target file(s), 4 already up-to-date, uploaded 1 new artifact(s).

サマリーは次の内訳で表示されます。

  • N 個のターゲットファイルをローカライズ — エンジンが新しい翻訳を生成し、CLI がそれを書き込みました。
  • N 件はすでに最新 — サーバー側のキャッシュヒット（ソースが一致し、ターゲットを再利用）。
  • N 個の新しいアーティファクトをアップロード — エンジンがこれまで見たことのないソース（バイナリ/大容量コンテンツは一度だけ保存され、以後は参照されます）。

ターゲットごとに失敗した場合は、--wait 使用時に CLI が失敗した各ターゲットのエラーを表示し、ゼロ以外の終了コードで終了します。CI で特に便利です。

text
✓ Run lrg_a8c...: localized 10 target file(s).
  2 target(s) failed:
    locales/de.json: rate limit on engine; retry later
    locales/fr.json: timeout

--estimate を使用する場合:

text
Estimating push cost…
› Estimated cost: ~$1.87 (12 target(s), ~48,000 output tokens — estimate, not a quote)
  de: ~$0.9350 (6 target(s), ~24,000 tokens)
  fr: ~$0.9350 (6 target(s), ~24,000 tokens)
  4 target(s) already up-to-date — no cost.
✓ Estimate complete — nothing was translated. Run `lingo push` to start the translation.

再試行の仕組み#

ロックファイルが更新されるのは、実行が完了したときだけです。実行が失敗またはキャンセルされた場合、ロックファイル内のソースハッシュは変わらないため、次の lingo push で同じ差分を再試行します。手動でリセットする必要はありません。

個別のターゲットが失敗していても、実行自体は完了することがあります。たとえば、あるロケールがタイムアウトした場合です。その場合、プッシュは成功した分を書き込み、新しいソースハッシュを記録したうえで、ゼロ以外の終了コードで終了します。そのため、通常の lingo push ではそれらのターゲットは再取得されません。影響を受けたソースに絞ったプッシュ（lingo push <pattern>）でもう一度実行してください。

翻訳が始まる前にエンジン側でエラーが発生した場合（認証、バリデーションなど）、何も書き込まれず、ロックファイルも変更されません。

よくあるパターン#

CI: マージ時に翻訳#

yaml
- run: lingo push --backfill-missing --yes --wait
- run: git add . && git commit -m "chore: refresh translations" && git push

--backfill-missing は安全な既定値です。何かを上書きすることはなく、不足している分だけを埋めます。--wait は翻訳が書き込まれるまで手順を待機させるため、コミット手順でコミットする内容を確実に用意できます。

一部の文字列をやり直す#

bash
lingo push --key auth.login --key billing.plan --wait

文言を変更したあと、そのキーだけを正確に再翻訳し、ファイル内のほかのキーはそのまま残します。

単一ファイルでの反復#

bash
lingo push docs/en/onboarding.md -f -y

コピーを大きく変更したあと、ソースを1つだけ再翻訳します。すばやく反復するため、プロンプトはスキップします。

新しいロケールの追加#

targetLocales の .lingo/config.json を増やしたあと:

bash
lingo push --backfill-missing

既存のものを再翻訳せずに、コーパス全体を新しいロケール向けに翻訳します。