新規登録
チェック・トラブル対処Read this article in English

ビルド間のローカライズファイル差分の読み方

差分(diff、バージョン管理システムが二つのバージョンのファイルを行単位で比較して示すもの)は、二つのビルド間でローカライズファイルに何が起きたかを把握するための、もっとも安価な手段の一つです。実行コストはゼロで、ファイルが素直な形をしていれば、どの文字列が動いたかを正確に教えてくれます。問題は、ローカライズファイルが必ずしも素直ではないことです。

一行の内容変更に対して赤と緑の壁が表示されるようなファイルは、もう何も有用な情報を伝えていません。差分から本当の価値を引き出すには、比較を実行するだけでなく、ファイルの書き方と読み方に一定の規律が必要です。

整形の揺れが差分を壊す理由

多くの差分ツールは、ファイルの構造を理解せず、テキストを行単位で比較します。JSONの出力インデントが2スペースから4スペースに変わったり、CSVの出力が今まで囲んでいなかったフィールドをクォートし始めたりすると、翻訳内容は一文字も変わっていないのに、ファイル内のすべての行が「違う」と表示されます。差分としては技術的に正しい(実際にバイト列は変わっている)のですが、本来の目的、つまり人間にレビュー対象を示すという役割は果たせていません。

キーの並び替えでも同じことが起きます。キーをアルファベット順にソートし直したり、データベースから別の行順でファイルを再生成したりすると、すべてのエントリが新しい行位置に移動します。行単位の差分はこれを「すべての行が削除されて追加し直された」と見なします。内容がバイト単位で同一のエントリであってもです。

// 変更前
{
  "menu.play": "Play",
  "menu.settings": "Settings"
}

// 変更後 — 実際に変わったのは "menu.settings" だけだが、
// アルファベット再ソートと整形の変更が重なり、差分は
// 両方の行が丸ごと書き換わったように表示される
{
    "menu.play": "Play",
    "menu.settings": "Options"
}

差分を意味のあるものに保つには

解決策は、より賢い差分ツールを使うことではなく、書き出し処理が何を変えてよいかを規律で縛ることです。キーが常に同じ順序(原文側のキー順、あるいは一度決めたら変えないアルファベット順)で書き出され、シリアライザが常に同じインデント幅とクォートのルールを使うなら、二回の書き出しの差分は実際の内容変更だけを反映します。書き出し処理は自動化されていることが多く、誰もそれを「ファイルの契約への変更」として扱わないまま気軽に調整されがちなので、これは見た目以上に重要です。

CSVで言えば、列の順序を固定すること、すべてのフィールドをクォートするか必要なフィールドだけクォートするか(RFC 4180ではどちらも許容されているので、どちらかに統一する)を固定すること、改行コードのスタイルを固定することです。JSONで言えば、キー順とインデント幅を固定することです。これは正しさの話ではありません — 整形し直したファイルも元のファイルも、パースすれば同じデータになります。あくまで、人間が読める差分を保つための話です。

原文の変更と訳文の変更を区別する

翻訳ファイルは通常、原文(文脈のため)と訳文(実際の翻訳)を並べて持っています。このファイルへの差分は、二つのまったく異なる意味を持ちえます。原文が変わった場合、翻訳は古くなっており再翻訳が必要です。訳文だけが変わった場合、誰かが翻訳を更新しており、それはレビューが必要です。

ファイル形式や差分の表示がこの区別を分かりやすくしてくれない場合、レビューする人は毎回それを目で再構築しなければならず、規模が大きくなるほど遅く、間違いも起きやすくなります。この二つを分離する(たとえば原文列と訳文列を独立に比較する、あるいはツール側で変更された行にどちら側が変わったかタグを付ける)だけで、長い赤緑の羅列一本が、目的別の短いリスト二本に変わります。

  • 原文が変わり訳文が変わっていない: 翻訳が古くなっている、再翻訳が必要
  • 原文が変わらず訳文が変わった: 翻訳が編集された、レビューが必要
  • 両方変わった: 原文更新に伴う再翻訳の可能性が高い、両方をレビュー
  • どちらも変わっていないが行が移動しただけ: 整形や並び順のノイズであり実質的な変更ではない

差分はレビューを置き換えるのではなく範囲を決めるために使う

きれいな差分の意味は、何を改めて見るべきかを教えてくれることにあり、同じくらい重要なのは、何を見なくてよいかも教えてくれることです。千件のエントリを持つ翻訳ファイルで、あるビルドではそのうち十二件しか変わっていないなら、残りの千件近くすべてを再レビューする必要はありません。差分こそが、それら988件は前回レビューされ承認された時点から変わっていないという証拠になります。

ただしこれは差分が信頼できる場合に限られ、結局は前述の整形の規律に戻ってきます。ノイズだらけの差分を「いつものこと」として扱っているチームは、毎回すべてを再レビューする(これは規模が大きくなると成立しない)か、何もレビューせず祈る(こちらの方が悪い)かのどちらかに陥りがちです。きれいな差分があって初めて、「変わった部分だけレビューする」という方針は勘ではなく安全な運用になります。

関連記事