i18n.lockロックファイル

i18n.lockは、不要な再翻訳を防ぎ、Lingo.dev CLIのパフォーマンスを最適化するために、コンテンツのチェックサムを追跡するロックファイルです。

i18n.lockは、ソースコンテンツと翻訳キーのチェックサムを保存し、翻訳実行間で何が変更されたかを識別します。その結果、新規または変更されたコンテンツのみが翻訳され、処理時間と翻訳コストが削減されます。

ロックファイルの構造

i18n.lockは、構造化されたYAML形式を使用してコンテンツのチェックサムを保存します。

version: 1
checksums:
  a07974ea09011daa56f9df706530e442:
    key: f8692d39317193acf0e2e47172703c46
  b18975fb19122ebb67g0ef817641f553:
    key: g9703e40428204bdf1f3f58283814d57

設定要素:

  • version — マイグレーション互換性のためのロックファイルスキーマバージョン
  • checksums — 翻訳されたコンテンツを追跡するコンテンツチェックサムとキーチェックサムのマップ
  • checksums.[content-hash] — 一意の識別子として機能するソースコンテンツのSHA-256ハッシュ
  • checksums.[content-hash].key — キー名変更の検出を可能にする翻訳キーのSHA-256ハッシュ

Lingo.dev CLIは、異なるキーチェックサムを持つ同一のコンテンツを検出した場合、既存の翻訳を保持します。再翻訳は行われず、キー構成の変更を許可しながら翻訳の一貫性が維持されます。詳細については、キー名変更をご覧ください。

ワークフロー統合

i18n.lockは、翻訳ワークフロー中に自動的に動作します。

初回実行 — 初期コンテンツチェックサムを含むロックファイルを作成します。

npx lingo.dev@latest run
# Creates i18n.lock with all source content checksums

ロックファイルの再作成 — ロックファイルをゼロから再作成します。

npx lingo.dev@latest lockfile --force
# Recreates i18n.lock with all source content checksums

ヒント: このコマンドを使用して、マージコンフリクト解決時にロックファイルを真の状態にリセットすることができます。重複排除は読み込みごとに自動的に実行されます。詳細はロックファイルの重複排除を参照してください。

以降の実行 — 変更されたコンテンツのみを処理します。

npx lingo.dev@latest run
# Compares current content against i18n.lock
# Translates only new or modified content

強制再翻訳 — ロックファイルの最適化をバイパスし、すべてのコンテンツを再翻訳してロックファイルを再作成します。

npx lingo.dev@latest run --force
# Ignores i18n.lock and retranslates all content

フローズン検証 — 翻訳の完全性を検証します。

npx lingo.dev@latest run --frozen
# Fails if any content requires translation
# Used in CI/CD to ensure complete translations

ロックファイルの重複排除

ロックファイルのYAMLには、同じチェックサムブロック内に重複した翻訳キーが含まれる場合があります。標準的なYAMLパーサーは最後の出現のみを保持するため、追跡の喪失や手動での解決が困難なマージコンフリクトにつながる可能性があります。

Lingo.dev CLIは、一貫したロックファイルの状態を維持するように構築されています。ロックファイルは読み込みごとに自動的に重複排除されます。チェックサムブロック内の重複キーが検出され削除されます。最後の出現が保持されます(最終書き込み優先、一般的なマージ動作に一致)。その結果、ロックファイルは内部的に一貫性を保ち、書き戻される内容と一致します。

実行タイミング — 重複排除は以下を含むすべての読み込み時に実行されます。

  • npx lingo.dev@latest run
  • npx lingo.dev@latest pull
  • npx lingo.dev@latest push
  • npx lingo.dev@latest status
  • npx lingo.dev@latest lockfile

重複が削除された場合、CLIは次のようなメッセージをログに記録します。Removed 3 duplicate entries from i18n.lock。ユーザーの操作は不要です。このステップは冪等であり、読み込みごとに安全に実行できます。困難な、または繰り返し発生するマージの問題については、npx lingo.dev@latest lockfile --forceを使用してロックファイルをゼロから再作成することもできます。

例 — 同じキーを変更した2つのブランチをマージした後:

version: 1
checksums:
  a07974ea09011daa56f9df706530e442:
    greeting.hello: abc123
    greeting.goodbye: def456
    greeting.hello: xyz789
    button.submit: ghi012
    button.submit: jkl345

読み込み時に、CLIは重複を排除し、各キーの最後の出現を保持します。

version: 1
checksums:
  a07974ea09011daa56f9df706530e442:
    greeting.goodbye: def456
    greeting.hello: xyz789
    button.submit: jkl345

2つの重複エントリが削除されました。

バージョン管理の統合

i18n.lockは、翻訳ファイルと共にバージョン管理にコミットする必要があります。

ロックファイルはLingo.dev CLIの差分翻訳システムの重要な部分であり、あらゆる規模のプロジェクトで実用的です。