翻訳済みの一行が、いつの間にか英語へ戻っていた — エージェントが触った文字列リソースを差分で守る

エージェントに values フォルダの整理を任せると、訳済みの値が静かに原文へ戻ることがあります。既定言語を正、各ロケールを差分として鍵単位で突き合わせ、欠落・戻し訳・書式引数の崩れだけを pre-commit で止める設計と実装をまとめました。

i18n³ Android²¹ localization³ pre-commit² Antigravity²⁶⁹

✦ プレミアム記事

先週、配信前の確認をしていて手が止まりました。中国語版の設定画面に、英語の "Notifications" がそのまま並んでいたのです。半年前に訳して、表示の崩れまで直したはずの一行でした。

直前に、エージェントへ values フォルダの整理を任せていました。重複した鍵をまとめ、使われていない鍵を消す——その作業のどこかで、訳済みの値がいくつか既定言語の原文へ戻っていました。差分は数百行に広がっていて、目視では追いきれません。

個人開発で壁紙アプリを多言語展開していると、文字列リソースはいつの間にか数百鍵まで膨らみます。私自身、翻訳の一行が静かに壊れても、ストアのレビューで指摘されるまで気づけないことがありました。だからこの種の事故は、人の目ではなく機械の目で止めたいと考えています。

並び替えは見逃し、値の変化だけを捕まえる

エージェントは XML を整えるとき、鍵を並べ替えたりインデントを揃えたりします。これ自体は害がありません。テキストの差分で守ろうとすると、こうした無害な整形まで違反として鳴ってしまい、すぐに誰も見なくなります。

止めたいのは、文字列の見た目ではなく意味が変わる三つの事象だけです。鍵が消えること、訳済みの値が原文へ戻ること、そして書式引数の数が既定とずれることです。最後のひとつは表示崩れでは済まず、String.format が IllegalFormatException を投げてその画面ごと落ちます。

事象	実行時に起きること	ゲートの判定
鍵の並び替え・整形	何も変わりません	許容（無視します）
ロケールから鍵が欠落	既定言語へフォールバックし、その一行だけ言語が混ざります	違反で停止
訳が原文へ戻る（戻し訳）	翻訳済みのはずの画面に英語が出ます	違反で停止
書式引数の個数不一致	その画面がクラッシュします	違反で停止

判定をテキスト差分ではなく「鍵→値の辞書」の比較に置くと、並び替えは自動的に同一とみなされ、値の変化だけが残ります。これが設計の核になります。

既定言語を正に、各ロケールを差分として読む

res/values/strings.xml を正（source）として扱い、res/values-en/・res/values-zh-rCN/ のような各ロケールを、正に対する差分として読みます。plurals は name#quantity の形に展開し、translatable="false" の鍵は対象から外します。

#!/usr/bin/env python3
"""res/values 以下の文字列リソースを HEAD と突き合わせ、
エージェントの編集による翻訳ドリフトを検出する pre-commit ゲート。"""
import re
import subprocess
import sys
import xml.etree.ElementTree as ET
from pathlib import Path
 
# 既定（source）の値と一致してよい鍵（ブランド名・記号的に原文一致が正のもの）
ALLOW_EQUAL = {"app_name", "ok_label", "brand_tagline"}
 
# %1$s / %d / %@ / {count} を順不同の多重集合へ正規化する
ARG_RE = re.compile(r"%(?:\d+\$)?[-#+ 0,(]*\d*(?:\.\d+)?([@a-zA-Z])|\{(\w+)\}")
 
def format_args(value: str):
    args = []
    for m in ARG_RE.finditer(value):
        if m.group(2) is not None:      # ICU 形式 {name}
            args.append("{}")
        else:                            # printf 系 %1$s / %d / %@
            args.append("%" + m.group(1))
    return sorted(args)
 
def parse_strings(xml_text: str):
    """strings.xml の本文を name->value 辞書に。plurals は name#quantity。"""
    out = {}
    if not xml_text.strip():
        return out
    root = ET.fromstring(xml_text)
    for s in root.findall("string"):
        name = s.get("name")
        if name and s.get("translatable") != "false":
            out[name] = "".join(s.itertext())
    for p in root.findall("plurals"):
        name = p.get("name")
        for item in p.findall("item"):
            out[f"{name}#{item.get('quantity')}"] = "".join(item.itertext())
    return out
 
def at_head(rel_path: str):
    """HEAD 時点の同ファイルを取得（新規ファイルは空辞書）。"""
    r = subprocess.run(["git", "show", f"HEAD:{rel_path}"],
                       capture_output=True, text=True)
    return parse_strings(r.stdout) if r.returncode == 0 else {}

itertext() を使うのは、<string> の中に <b> などの装飾タグが混ざっていても、表示文字列を取りこぼさないためです。エージェントが整形のついでにタグ構造を変えても、結合後の文字列が同じであれば同一として扱えます。

✦

ここまでお読みいただきありがとうございます。

この記事の続きを読む

この先には、実装コードやベンチマーク結果など、実務でお役に立てる内容をご用意しています。このサイトは広告を掲載しておらず、サーバーや開発にかかる費用はメンバーの皆様のご支援で成り立っています。もしお役に立てていましたら、ご支援いただけますと大変ありがたいです。

この記事で得られること

✦翻訳リソースを既定言語=正・各ロケール=差分として鍵単位で照合し、消えた鍵・原文へ戻った訳・壊れた書式引数を機械で検出する設計

✦strings.xml と xcstrings をまたいで HEAD と突き合わせ、未翻訳フォールスルーとプレースホルダ個数の不一致を pre-commit で止める実装

✦並び替えは許容して値の変化だけを違反とする差分ルールと、CIへ載せるときの終了コード契約・除外鍵の設計

Stripe による安全な決済 · いつでもキャンセル可能

✦

この記事を購入する

この先の内容をすべてお読みいただけます。一度のご購入で、いつでも何度でもアクセスできます。このサイトは広告を掲載しておらず、皆さまのご支援がサーバー費用などの運営を支えています。

または

メンバーシップなら全記事が読み放題 →

止めるのは三つだけ——欠落・戻し訳・書式引数

判定を増やすほど誤検知が増え、ゲートは形骸化します。私は、人手の正当な修正と確実に区別できる三つだけに絞っています。

戻し訳の判定がいちばん要です。「いまの値が原文と一致し、かつ HEAD の時点では原文と違っていた」ときだけ違反とします。最初から原文と同じだった鍵（短い記号やブランド名）は対象外になり、過去に訳されていた一行が原文へ戻った瞬間だけを捕まえられます。

def check_locale(default_now, base_loc, cur_loc, locale):
    v = []
    # 1. 欠落: HEAD にあった鍵が、いまのロケールから消えている
    for key in base_loc.keys() - cur_loc.keys():
        v.append((locale, key, "removed", "HEAD にあった鍵が消えています"))
    # 2. 戻し訳: 訳済みだった値が、既定言語の原文へ戻っている
    for key in cur_loc.keys() & base_loc.keys():
        src = default_now.get(key)
        if src is None or key in ALLOW_EQUAL:
            continue
        if cur_loc[key] == src and base_loc[key] != src:
            v.append((locale, key, "reverted", "訳が既定言語の原文へ戻っています"))
    # 3. 書式引数: 個数・種類が既定と一致しない（クラッシュ源）
    for key, val in cur_loc.items():
        src = default_now.get(key)
        if src and format_args(val) != format_args(src):
            v.append((locale, key, "format",
                      f"書式引数が不一致 {format_args(src)} != {format_args(val)}"))
    return v

書式引数は順番ではなく多重集合で比べます。Android では %1$s のように位置を指定できますが、ここで守りたいのは「引数の個数と種類がずれてクラッシュする」ことの防止です。位置の入れ替えは翻訳上むしろ正しいので、種類の集合だけを照合します。

違反種別	成立条件	なぜ止めるか
removed	HEAD の鍵が現在のロケールに無い	言語の混在を防ぐため
reverted	現在値=原文かつ HEAD値≠原文	静かな未翻訳化を防ぐため
format	書式引数の多重集合が既定と不一致	実行時クラッシュを防ぐため

ステージされた時だけ走らせる

ドライバはロケール用ディレクトリを総当たりし、違反があれば終了コード 1 で抜けます。CI でも同じスクリプトをそのまま使えるよう、出力は標準エラーへ、合否は終了コードで返します。

def main():
    res = Path("app/src/main/res")
    default_now = parse_strings((res / "values/strings.xml").read_text("utf-8"))
    failures = []
    for d in sorted(res.glob("values-*")):
        f = d / "strings.xml"
        if not f.exists():
            continue
        locale = d.name.removeprefix("values-")
        rel = str(f)
        failures += check_locale(default_now, at_head(rel),
                                 parse_strings(f.read_text("utf-8")), locale)
    for locale, key, kind, msg in failures:
        print(f"✗ [{locale}] {key} — {kind}: {msg}", file=sys.stderr)
    if failures:
        print(f"\n翻訳ドリフト {len(failures)} 件。コミットを止めました。", file=sys.stderr)
        sys.exit(1)
    print("✓ 翻訳リソースのドリフトはありません")
 
if __name__ == "__main__":
    main()

pre-commit フックでは、文字列リソースがステージされたときだけ走らせます。毎回のコミットで全件を舐めると遅くなるので、git diff --cached で対象を絞ります。

#!/usr/bin/env bash
# .git/hooks/pre-commit
set -euo pipefail
if git diff --cached --name-only | grep -qE 'res/values(-[A-Za-z+-]+)?/strings\.xml$'; then
  python3 tools/i18n_drift_gate.py || {
    echo "翻訳リソースの確認に失敗しました。修正してから再コミットしてください。" >&2
    exit 1
  }
fi

私はこの判定を pre-commit と CI の両方に置くことを推奨します。手元での取りこぼしを CI が拾い、エージェントが無人で開いた変更も、配信パイプラインの手前で同じ目を通せるからです。原文一致が正しい鍵は ALLOW_EQUAL に明示して、除外の理由をコードに残しておきます。

八言語・約540鍵で計測してわかったこと

実際に、AdMob の同意ダイアログまわりの文言を整理する一週間、このゲートを挟んで運用してみました。対象は八言語、配信あたり約540鍵です。エージェントには重複の統合と未使用の削除を任せ、その出力をゲートに通しました。

検出種別	件数（1週間）	気づけた場面
戻し訳（reverted）	3件	コミット前（従来は配信後にレビューで発覚）
書式引数の不一致（format）	1件	コミット前（クラッシュ前）
鍵の欠落（removed）	2件	コミット前
並び替え・整形の誤検知	0件	辞書比較なので鳴りません

数字そのものは小さく見えるかもしれません。けれども、書式引数の不一致が一件あれば、その言語のユーザーには特定の画面が必ず落ちます。Google Play のレビューで一行の苦情として届くより前に、手元で止められた意味は小さくありませんでした。誤検知が0件だったことも、ゲートを使い続けられた理由です。

iOS の文字列カタログにも同じ目を

iOS の文字列カタログ（.xcstrings）は JSON なので、同じ考え方をそのまま移せます。鍵ごとに各ロケールの stringUnit が並び、state に translated や needs_review が入ります。needs_review のまま配信に乗る事故も、ここで拾えます。

import json
 
def parse_xcstrings(path, target):
    """xcstrings から target ロケールの 鍵->(値, 状態) を取り出す。"""
    data = json.loads(Path(path).read_text("utf-8"))
    out = {}
    for key, entry in data.get("strings", {}).items():
        unit = entry.get("localizations", {}).get(target, {}).get("stringUnit")
        if unit:
            out[key] = (unit.get("value", ""), unit.get("state", ""))
    return out
 
def review_pending(path, target):
    return [k for k, (_, st) in parse_xcstrings(path, target).items()
            if st == "needs_review"]