XML

宣言、コメント、属性、レイアウトをバイト単位で保持しながら、あらゆるXML文書のテキストを元の位置で翻訳します。

xmlファイルハンドラーは、コンテンツのエクスポート、ヘルプファイル、独自のリソース形式など、専用の形式では対応していないXML文書のテキストを翻訳します。翻訳はソースファイルのコピーに書き込まれるため、宣言、DOCTYPE、コメント、処理命令、属性、名前空間、空白文字は元のまま保たれます。変更されるのは、翻訳するテキストと指定した属性だけです。

Androidリソース、XLIFF、Appleの複数形辞書もXMLですが、それぞれAndroid、XLIFF、Apple stringsdictという専用の形式があります。これらはキー、複数形、各翻訳の状態を認識するため、該当するファイルには専用の形式を使用してください。

XML翻訳の設定 #

ファイルが汎用XMLとして翻訳されるのは、そのファイルのエントリで"format": "xml"を設定した場合だけです。Androidのstrings.xmlも同じ拡張子を使うため、拡張子が.xmlというだけでは形式は選択されません。エントリに形式が指定されていない.xmlファイルは、CLIではメッセージを表示してスキップされ、GitHub Appでもスキップされます。

json
{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "files": [{ "pattern": "content/en/*.xml", "format": "xml" }]
}

この設定では、content/en/guide.xmlに対してcontent/de/guide.xmlとcontent/fr/guide.xmlが書き込まれます。出力先のパスには、出力パスで説明しているJSONと同じルールが適用されます。それ以外の配置はtargetPathで指定します。ファイルは、パターンが最初に一致したエントリに属します。そのため、Androidリソースは"format": "android"を指定した専用エントリに分け、XMLのエントリにはAndroidリソースに一致しないパターンを指定してください。同じ設定をCLIとGitHub Appで使用できます。

翻訳の対象 #

テキストを含む各要素が、1つの翻訳単位になります。他の要素、コメント、空白文字だけを含む要素は、それ自体では翻訳単位にならず、代わりに子要素が読み取られます。

xml
<?xml version="1.0" encoding="UTF-8"?>
<help>
  <!-- shown on the settings page -->
  <topic id="sync">
    <title>Sync your files</title>
    <p>Click <b>Sync</b> to upload your <a href="/files">files</a> now.</p>
  </topic>
</help>

ここではtitleが1つの翻訳単位、pが別の翻訳単位です。コメント、id、hrefは翻訳に送信されません。

  • インライン要素。 上のpのように内部に要素を含むテキストは、文全体が1つの翻訳単位になります。インライン要素は、移動はできても変更はできないプレースホルダーとしてモデルに渡されます。これにより、翻訳先の言語に適した位置にSyncとfilesを配置できます。こうしたテキスト内のコメントや処理命令も、同じ方法で保持されます。
  • 空白文字。 要素間のインデントなど、空白文字だけで構成されるテキストは送信されません。テキストの前後の空白文字はファイル内に保持され、テキスト内部の空白文字はそのまま送信されます。翻訳によってテキストの前後に追加された空白文字は削除されます。
  • CDATA。 単一のCDATAセクションで構成されるテキストは、翻訳後もCDATAセクションとして書き戻されます。他のテキストに隣接するCDATAセクションは、そのテキストの一部として扱われ、エスケープして書き戻されます。XMLでは、どちらも同じように読み取られます。
  • 参照。 &amp;、&lt;、&gt;、&quot;、&apos;、および&#169;などの文字参照は、翻訳前にデコードされます。&brand;や&product-name;など、DOCTYPEで宣言されたエンティティはプレースホルダーと同様に保護され、そのまま書き戻されます。
  • 文章ではない値。 数字のみのテキスト、URL、ISO形式の日付、英数字で構成される22文字の識別子は、翻訳されずにすべての翻訳先にコピーされます。

要素名とパスは、大文字と小文字の区別や名前空間の接頭辞も含め、記述どおりに読み取られます。

属性の翻訳 #

属性値は、translateComponentPropsで指定しない限り翻訳されません。文字列で指定すると、すべての要素の該当属性が対象になります。componentを持つオブジェクトで指定すると、指定した要素の該当属性だけが対象になります。

json
{
  "pattern": "content/en/*.xml",
  "format": "xml",
  "translateComponentProps": ["title", { "component": "item", "props": ["label"] }]
}

この設定では、すべてのtitle属性と、<item>要素のlabel属性が翻訳されます。名前は記述どおりの完全一致で照合されるため、x:titleとTitleは別の属性として扱われます。空の値はスキップされます。識別子、リンク、xml:lang、名前空間の宣言は、明示的に指定した場合に限り翻訳されます。誤って指定すると、ファイルの解釈が変わります。

翻訳の書き込み方法 #

翻訳されたテキストでは、&、<、>がエスケープされます。翻訳された属性では、&、<、属性値を囲む引用符と同じ文字がエスケープされます。タブと改行は、XMLで保持されるように文字参照として書き込まれます。翻訳されたCDATAセクション内の]]>は、2つのセクションに分割されます。翻訳内の改行には、ファイル自体の改行コードが使われます。XMLに含められない制御文字は、翻訳から削除されます。

宣言でencoding="ISO-8859-1"などのUTF-8以外のエンコーディングが指定されている場合、翻訳内のASCII以外の文字は、éを&#xE9;とするように、文字参照として書き込まれます。これにより、出力先のファイルをそのエンコーディングでも読み取れます。ファイルの読み込みはUTF-8で行われるため、別のエンコーディングを宣言し、アクセント付き文字を生のバイトで含むファイルは、最初の該当箇所の位置を示して処理に失敗します。そのファイルには何も書き込まれません。UTF-8で保存するか、該当する文字を文字参照で記述してください。

このハンドラーは、xml:langをはじめ、文書の言語を示す属性を変更しません。ビルド時に更新するか、テキストを含む属性であればtranslateComponentPropsで指定してください。

キーと翻訳の再利用 #

各翻訳単位のキーには、XPathのように記述した要素パスが使われます。たとえば/help/topic/title、/list/item[2]、属性の場合は/menu/item[1]/@labelです。位置が付くのは、同じ名前の兄弟要素がある場合だけです。これらのキーは、ジョブ内とStudioで翻訳単位を識別するために使われます。

ユニットのテキストと要素パス(位置を除く)が前回のプッシュ以降変わっておらず、翻訳でも原文のインライン要素とその入れ子構造が保たれていれば、既存の翻訳が維持されます。翻訳先の言語では語順の都合で要素の並べ替えが必要になることも多いため、翻訳内でこれらの要素の順序が変わっていても問題ありません。インライン要素の翻訳済み属性は、その要素と一緒に移動します。要素を挿入すると、新しい要素だけが翻訳されます。後続の要素は、位置が変わっても既存の翻訳が維持されます。翻訳内のインライン要素が原文と一致しなくなった場合、たとえば翻訳側で誰かが要素を削除したり、別の要素の内側に移動したりした場合は、その翻訳が再翻訳されます。

適用されないオプション #

XMLにはキーのルールがありません。CLIとGitHub Appは、lockedKeys、preservedKeys、ignoredKeys、keyColumn、injectLocale、translateFrontmatterFieldsのいずれかが設定されたXMLエントリを拒否します。そうしないと、設定したオプションが無視されたままファイルが翻訳されてしまうためです。lockedPatternsも、Javaプロパティ以外のすべての形式と同様に拒否されます。

lingo push --keyは、XMLファイルをメッセージ付きでスキップし、選択された他のファイルをプッシュします。

無効なXML #

整形式でないXMLファイルは、最初の問題の行と列を示して処理に失敗します。たとえば、タグが閉じられていない、タグの対応が取れていない、&がエスケープされていない、ルート要素が2つある、ルート要素の外にテキストがある、といった場合です。ファイルの末尾で複数のタグが閉じられていない場合は、代わりにそのタグ名がエラーに表示されます。要素の入れ子が256階層を超えるファイルも処理に失敗します。そのファイルには何も書き込まれず、既存の出力先ファイルはそのまま保持されます。出力先が整形式でない場合も同様に処理に失敗し、対象のロケールが表示されます。XMLを修正してから、もう一度プッシュしてください。