JSON ローカライズの際、どの部分を翻訳できて、どの部分は変更してはいけないのか?

よくあるJSONローカライズの失敗は、ページボタンが英語に変更されているのに、対応する設定項目を見つけられないことです。 一般的な理由は、オブジェクト内のすべての文字列がトランスレーターに引き渡されて処理され、キー名、ルーティング、ビジネスエンコーディングも変更されるからです。 この記事は、国際化設定を担当する開発者およびローカリゼーション担当者向けに書かれており、受け入れを行う前にまず翻訳可能なフィールドパスをどのように定義するかを説明します。

この例では、処理方法を示すために合成サンプルを使用しており、コードは隔離された環境でチェックされていますが、これはすべての実際のファイルや製品のパフォーマンスを保証するものではありません。重要な書類を処理する前に、原本を保管し、本文の境界と許容事項に従って確認してください。

JSON ローカリゼーション中に翻訳できるものは何ですか?一文の結論

事前にリストされたコピーライティング パスのみが翻訳されます。キー名、ルーティング値、およびビジネス コードは変更されず、変更されていない部分が実際に変更されていないことを確認するために受け入れチェックリストが使用されます。

すべての文字列を走査するのではなく、フィールド パスから開始します。

buttons.save をアドレスとして扱うことは、文字列「save」を見つけたときに置き換えるよりも信頼性が高くなります。同じ文がインターフェイスのコピー、ログ サンプル、テスト ケースに同時に出現する場合があり、3 か所すべてで翻訳が必要なわけではありません。

パスはタプルまたは JSON ポインターを使用して明確に表す必要があります。単純にドットで繋ぎ合わせる場合、キー名自体にドットが含まれていると曖昧さが生じます。

次の例では、2 つの特定のパスのみを制限し、他のコンテンツはそのままにします。これはこの記事のローカリゼーション戦略であり、JSON 形式自体の要件ではありません。合成サンプルには、インターフェイス テキストと、境界チェックを容易にするために変更してはいけないルーティング値の両方が含まれています。

一度に変更できるのは明示的に許可された値のみです

import copy

source = {"buttons": {"save": "保存", "cancel": "取消"},
          "route": "/settings", "version": 1}
approved = {("buttons", "save"): "Save",
            ("buttons", "cancel"): "Cancel"}

def apply_texts(document, replacements):
    result = copy.deepcopy(document)
    for path, translated in replacements.items():
        if not path or not isinstance(translated, str):
            raise ValueError("invalid replacement")
        parent = result
        for key in path[:-1]:
            parent = parent[key]
        key = path[-1]
        if key not in parent or not isinstance(parent[key], str):
            raise ValueError("target must be an existing string")
        parent[key] = translated
    return result

result = apply_texts(source, approved)
assert result["buttons"]["save"] == "Save"
assert result["route"] == source["route"]
assert source["buttons"]["save"] == "保存"
try:
    apply_texts(source, {("version",): "one"})
except ValueError:
    pass
else:
    raise AssertionError("numeric field must be rejected")

この例ではオブジェクト レベルのみを示しており、配列のインデックス付けは実装されておらず、翻訳サービスも呼び出していません。実際のパイプラインに送信する場合、許可されるパスのリストは変換前に決定される必要があり、変換を生成する当事者が同時に自身の変更範囲を拡張することは許可されません。

ディープ コピーは、入力オブジェクトがその場で変更されるのを防ぐことができますが、トランザクション システムではありません。永続性は依然として個別に設計する必要があります。

受け入れられるかどうかは変更されていない部分に依存します

単に「対象言語が現れた」という確認だけでは不十分です。 ソースファイルのハッシュやパスリストも保存する必要があります。 ソースファイルが更新されパスが削除されている場合、古い翻訳は類似したフィールド名で自動的に書き換えられません。

配列、null 値、重複キーは別々に考慮すべきです

• Array:要素を並べ替えた後、インデックスが元のテキストを指ささなくなることがあります。 安定したIDが存在する場合、そのIDはマッピングのために優先されます。
• Null value: nullは空文字列ではなく、翻訳を容易にするために「empty」というテキストに置き換えるべきではありません。
• 重複鍵:通常のJSON解析では完了後に重複鍵情報が失われる可能性があります。 重複キーを拒否したい場合は、翻訳が完了した後ではなく、解析フェーズで処理すべきです。 参考文献:Python JSON ドキュメント。

この例は、よく構造化された構成のローカリゼーションに適しており、ランダムなJSON自動翻訳機には適していません。 翻訳受理時には、まず構造と保護されたフィールドが変わらないことを確認することから、言語が自然かどうかを議論し、検査順序が明確になります。

📊 コア比較

🎯 どの方法があなたに合いますか?

もし......

• インターフェース設定ファイルを維持する。ボタンテキストを翻訳可能にし、プログラム設定を変更しない場合は、フィールドパスホワイトリストを使用し、翻訳前にパスリストを確認してください。
• 配列要素の配置変更が可能です;依存性インデックスではなく安定IDを優先してマッピングすること。
• ソースファイルは継続的に更新されます。ソースファイルのハッシュとパスリストを保存してください。パスが消えた場合、エラーが発生し、古い翻訳は自動的に書き換えられません。
• 実際の文書の配達を担当する場合は、許可された経路、原文、翻訳の校正チェックリストを作成し、各項目を確認してください。

❓ よくある質問(FAQ)

1. なぜすべての文字列を直接JSONで翻訳しないのですか?

同じ文字列が同時にインターフェースコピー、プログラムキー、またはビジネスコードであることがあるからです。 各文字列がトランスレーターに渡されると、キー、ルーティング、ビジネスエンコーディングも同時に変更され、プログラムが設定オプションを見つけられなくなります。

2. ドットマークで縫い目を縫う際の問題点は何ですか?

キー名自体にポイントが含まれている場合、ポイント連結は曖昧さを引き起こします。 原文では、タプルやJSONポインタのような曖昧さのない表現の使用が推奨されています。

3. 翻訳に十分なターゲット言語が含まれているか確認すればいいのですか?

まだ足りなかった。 また、キー名セットがソースファイルと一致しているか、不正パスの値が変わっていないか、ターゲットフィールドがまだ文字列であるか、欠損パスに明確なエラーがあるかも確認してください。

4. null:「空」という文を「空」に置き換えてもらえますか?

いや、できない。 nullは空文字列ではなく、翻訳の便宜のためにテキストに置き換えるべきではありません。

5. 配列変換のマッピングには何を使うべきでしょうか?

安定したIDが存在する場合、そのIDはマッピングのために優先されます。 インデックスのみに依存するため、要素を並べ替えた後の誤ったテキストに対応することがあります。

📝 概要

JSON翻訳を設定する前に、まず許可された翻訳経路を明確にし、その後、アクセプタンスチェックリストを使って変更されていない部分をチェックしてください。 これにより、ミスが起きたときに問題を特定しやすくなります。

今すぐ体験:元のフォーマットを保ちながら翻訳を始めるために文書をアップロードしましょう