CLI v0 の Lockfile

従来のソース基準状態を使って保留中の変更を把握し、未完了の翻訳を見落とさずに復旧する方法を説明します。

i18n.lock は、v0 が変更のないソースと翻訳が必要なテキストを区別するために使われます。対応するソースおよび承認済みの翻訳先ファイルと一緒に管理してください。翻訳先に人が加えた編集をすべて記録するものでも、翻訳の正しさを証明するものでもありません。

ファイルに記録される内容 #

lingo.dev@0.138.10 では、ファイルは YAML 形式で、version: 1 と checksums のマッピングを含みます。外側の各セクションは、処理されたパスパターンをハッシュ化したものです。その中の各エントリは、ソースキーと、MD5 に基づくソース値のチェックサムを対応付けます。これらのエントリは手動で作成せず、CLI に管理させてください。

チェックサムが変わると、既存のキーが翻訳対象になります。また、ソース値のハッシュが一致すれば、同じ処理コンテキスト内で新しいキーと削除されたキーを関連付け、名前変更前の翻訳を再利用できます。どちらの仕組みも、ファイルをまたいで無制限に使える翻訳メモリではありません。

翻訳と基準状態の置き換えを区別する #

操作処理内容
lingo run算出された差分を翻訳し、ソースの状態を更新します。
lingo run --force通常の差分に依存せず、選択した出力を再生成します。
lingo lockfileソース状態の不足しているセクションを追加し、内容がすでにあるセクションは変更しません。
lingo lockfile --force翻訳先の翻訳は行わず、現在のファイルに基づいてソースのチェックサムを置き換えます。
lingo run --frozen翻訳せずに同期状態を確認します。ただし、基準状態がない場合は先に初期化します。

フランス語の翻訳が承認された後で、英語のソースが変更されたとします。lockfile --force でチェックサムを置き換えると、フランス語には古い意味が残っている可能性があっても、新しい英語が基準状態として記録されます。そのため、同期チェックの失敗を解消する通常の手段として、再構築を使わないでください。

翻訳先ロケールやキーで範囲を限定して実行すると、既存の共有ソース基準状態を更新せずに翻訳が書き込まれることがあります。その後の通常実行で同じソースの変更が再び処理され、範囲限定の実行後に加えた修正が上書きされる可能性があります。共有の基準状態を更新する前に、関連するロケールの出力を慎重に照合し、整合性を確保してください。

複数のロケールにわたるソースの変更を確定する場合:

  1. 影響を受ける出力に未完了のものがある間は、ソースのリビジョンを固定し、i18n.lock を保持してください。通常のプロジェクト全体の更新には lingo run を使い、出力ごとに作業とレビューを分ける必要がある場合は、ドキュメントに記載された範囲を限定した実行を使ってください。
  2. ソースのチェックサムの置き換え対象となる、すべてのロケールの出力を確認してください。直近の範囲限定実行で変更されなかった出力も対象です。失敗を解消し、承認済みの手動修正をそのソースと照合して、整合性を確保してください。古いままの出力や状態が不確かな出力が一つでもあれば、共有の基準状態は更新せず、保留にしてください。
  3. 範囲を限定した作業で既存の基準状態が変更されておらず、対象の出力がすべて承認済みになったら、意図したプロジェクトルートから lingo lockfile --force を実行してください。この操作は翻訳を行わずにソースのチェックサムを置き換えます。前述のレビューを省くために使ったり、最後に指定した翻訳先ロケールによって置き換えの範囲も制限されると考えたりしないでください。
  4. Lockfile の差分を確認し、該当するソースのリビジョン、対応する承認済みの翻訳先すべて、および i18n.lock をまとめてコミットしてください。その後、lingo run --frozen で確定済みの基準状態との同期を確認できます。ただし、翻訳先が最新であることや、翻訳品質を確認できるわけではありません。

i18n.lock がない場合、凍結モードは厳密には読み取り専用ではありません。先にチェックサムを初期化することがあり、翻訳先のキーが存在するだけでは、その内容が最新であることを証明できません。凍結モードのチェックに合格したことを同期の証拠とみなす前に、信頼できるソースと翻訳先の組み合わせを確立してください。

欠落や競合のある状態から復旧する #

Lockfile がない場合でも、v0 が既存の翻訳先をすべて再生成するとは限りません。以前のチェックサムがなければ、既存の値を保持することがあります。新しく作成された基準状態を受け入れる前に、ソースと翻訳先の対応に不確かな点がないか確認してください。このような既存翻訳の取り込みについては、既存の翻訳で説明しています。

マージ競合がある場合は、まず両方のブランチのソースと翻訳先の変更を照合し、整合性を確保してください。可能であれば、信頼できる Lockfile を復元してください。再構築が必要な場合は、実際のソースと翻訳先の組み合わせをレビューしてください。再構築で記録されるのはソースの状態であり、翻訳先が最新であることではありません。

従来の YAML 修復処理では、重複するエントリのうち最後のものを残し、削除内容を報告します。これで解消されるのは構文上の重複であり、どちらのブランチの表現が正しいかは判断されません。修復済みのファイルを承認済みの出力とともにコミットする前に、競合している値を確認してください。