翻訳の対象範囲
差分更新、対象ロケールの網羅、意図的な再生成をそれぞれ区別しながら、ファイルと安定キーを選択します。
ローカライゼーションの変更は、ファイル、言語、メッセージ群に影響することがあります。CLIでは、それぞれを異なる方法で選択します。プロジェクト設定でファイルと対象ロケールを選び、位置引数のパターンでファイルと処理計画の範囲を絞り込み、--keyで安定キーを指定してメッセージを選択します。
ファイルの対象範囲で処理計画が変わる #
lingo push 'locales/en.json' --waitこのパターンは、設定済みのソースファイルを絞り込みます。翻訳先を別ファイルに保存する形式では、このコマンドは存在しない翻訳先を作成し、既存の翻訳先はソースに変更があってもそのまま残します。設定済みロケールの一部が処理対象から外れる場合は、既存のソース基準状態を保持するため、後で通常のプッシュを実行したときに、その編集内容を処理できます。基準状態がまだない場合は、初期化できます。
通常のソース編集には、オプションを付けずにlingo push --waitを使用します。翻訳先を別ファイルに保存する形式で、意図的にファイル全体を置き換えるには、位置引数で対象範囲を指定し、--forceを付けます。ただし、強制実行では既存の翻訳先の文脈が破棄されます。XCStringsカタログでは、埋め込まれた翻訳を引き続き再利用できます。カタログの更新を参照してください。翻訳先は常にtargetLocalesで決まります。プッシュには--localeフラグも--target-localeフラグもありません。
安定キーによる再生成 #
lingo push 'locales/en.json' --key 'checkout.title' --key 'checkout.submit' --wait複数の対象を選択するには、--keyを繰り返し指定します。キーはcheckout.titleやitems[0].titleのようにドットや角括弧で記述するパスです。オブジェクトを選択すると、その配下のすべての文字列が対象になります。そのため、auth.loginはauth.login.titleを含みますが、auth.login_urlは選択しません。*は任意の一つのセグメント全体を、[]は配列の全要素を表します。auth.log*のような部分的なワイルドカードは使用できません。$.または$[で始まるパターンは、JSONPathクエリとしてそのまま渡されます。ワイルドカードを含むパターンは引用符で囲んでください。
以前のCLI向けに/を使って記述したパターンも使用できます。/を含むパターンは/だけで分割され、各名前は一つのまとまりとして扱われます。auth/loginはauth.loginと同じキーを選択し、common/error.messageはcommon配下のキーerror.messageを選択します。legal/Terms%20of%20useのようにパーセントエンコードされた名前はデコードされます。/を含まないパターンはドット区切りのパスとして扱われ、デコードされません。そのため、エンコードされた単一の名前は$['Terms of use']のようにJSONPathで記述してください。/を含むパターンはすべてこの方法で解釈されるため、名前に/を含むキーには、$.routes['/about'].titleのようなJSONPathが必要です。この形式では、*は任意の一つの名前全体を表します。また、auth/*のように末尾に*を付けると、以前のCLIと同様に、auth直下の値を選択しますが、そこに入れ子になっているオブジェクトや配列は選択しません。末尾の/**は、その直前の名前の配下にあるすべてを対象にします。auth/**はauthと同じで、auth/*/**は、auth/*では対象外になるauth配下のオブジェクトや配列も含みます。items/0のような数値は、文書の構造に応じて、配列要素またはオブジェクトのキー"0"を選択します。名前の中のグロブ、末尾以外の**、角括弧、a//bのような空の名前は使用できません。
| 形式 | キーによる対象範囲の指定 |
|---|---|
| JSON/JSONC、PHP、TypeScript、Javaプロパティ | ソースの値に変更がないものも含め、選択した文字列を再生成します。 |
| YAML/ルートキー付きYAML | 安定キーを選択します。ただし、選択した文字列に変更がなければ、既存の翻訳を再利用できます。 |
| gettext、ARB、Apple strings、XCStrings、CSV、Android、XLIFF | 未対応です。--keyを指定すると、エラーでプッシュが停止します。 |
| Markdown、MDX、Markdoc、HTML、OpenAPI YAML、SubRip、プレーンテキスト、Apple stringsdict | 安定キーがないため、メッセージを表示してスキップします。 |
キーによる再生成には、既存の翻訳先が必要です。翻訳先が存在しないロケールや安定キーのない形式は、新規作成せず、メッセージを表示してスキップします。バックフィルは、存在しない通常のファイルを補いますが、既存ファイル内の欠落は補いません。--forceを追加しても、キーで対象範囲を指定した処理計画は変わらず、YAMLの既存翻訳の再利用も妨げません。
キーによる再生成では、push --waitで結果を取得しても、別途プルで取得しても、ソース全体の基準状態は変わりません。そのため、保留中の通常のソース編集は、次回の通常のプッシュでも処理されます。
指針の変更後に再生成する #
ローカライゼーションエンジンの用語集やルールを編集しても、ソースファイルのバイト列は変わりません。そのため、通常のプッシュでは何も処理されない場合があります。JSON、JSONC、TypeScript、PHPでは、影響を受ける安定キーを選択してください。YAMLで狙った箇所だけを修正するには、翻訳先を直接編集します。または、承認済みの翻訳先を保存したうえで、対象範囲を絞ったファイル全体の--forceを--keyなしで実行し、再生成します。この置き換えでは周辺のメッセージも変わる可能性があるため、生成されたファイル全体を確認してください。キー制御は、再構築時にどのソース値や翻訳先の値を残すかを決めるもので、処理対象を選択するものではありません。
大規模な変更では、確認と復元ができる程度に対象範囲を絞り、送信前に見積もりを行ってください。見積もりでは、必要なファイルをアップロードして処理を計画しますが、翻訳ジョブは作成しません。
単一のロケールを再翻訳する #
言語ごとにファイルが分かれているプロジェクトでは、その言語の翻訳先を削除し、バックフィルで不足するファイルを補います。先に、保留中のソース更新を完了し、承認済みの翻訳を保存してください。対象を絞ったパージでは、他の言語のソース基準状態とLockfileのエントリが保持されます。
locales/en.jsonにソースが設定されている場合は、フランス語の翻訳先の削除をプレビューします。
lingo purge --locale fr --file locales/en.json表示されたパスを確認します。意図した翻訳先であれば、削除を確定し、不足する翻訳を作成します。
lingo purge --locale fr --file locales/en.json --yes
lingo push --backfill-missing --waitlocales/en/*.jsonのようなグロブを使用する設定では、両方のパージコマンドで--fileオプションを繰り返し指定し、具体的なソースパスを渡してください。パージ自体はグロブを展開しません。フランス語の翻訳先を再生成したいソースをすべて含め、バックフィルの前に、他の翻訳先ファイルが欠けていないことを確認してください。バックフィルは、設定済みの翻訳先のうち、存在しないものをすべて作成します。
完了後、フランス語の出力を確認し、更新されたLockfileとともにコミットします。他の言語の既存の翻訳先ファイルは変更されません。選択ルールについては、パージを参照してください。この手順は、ソースとすべての対象ロケールが一つのファイルを共有するXCStringsカタログには適用できません。