XML
Übersetze den Text beliebiger XML-Dokumente direkt in der Datei – Deklaration, Kommentare, Attribute und Layout bleiben Byte für Byte erhalten.
Der xml-Dateihandler übersetzt den Text von XML-Dokumenten, für die es kein eigenes Format gibt, etwa Inhaltsexporte, Hilfedateien oder benutzerdefinierte Ressourcenformate. Er schreibt jede Übersetzung in eine Kopie der Quelldatei. Dabei bleiben Deklaration, DOCTYPE, Kommentare, Verarbeitungsanweisungen, Attribute, Namensräume und Whitespace unverändert. Nur der übersetzte Text und die von dir angegebenen Attribute ändern sich.
Android-Ressourcen, XLIFF und Apple-Pluralwörterbücher basieren ebenfalls auf XML, haben aber eigene Formate: Android, XLIFF und Apple stringsdict. Verwende für solche Dateien die jeweiligen Formate, denn sie berücksichtigen Schlüssel, Pluralformen und den Status jeder Übersetzung.
XML-Übersetzung konfigurieren #
Eine Datei wird nur dann als generisches XML übersetzt, wenn ihr Dateieintrag "format": "xml" festlegt. Die Dateiendung .xml allein bestimmt kein Format, da eine Android-strings.xml dieselbe Endung verwendet. Gibt der Eintrag einer .xml-Datei kein Format an, überspringt die CLI sie mit einer Meldung. Auch die GitHub App überspringt sie:
{
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"files": [{ "pattern": "content/en/*.xml", "format": "xml" }]
}Damit werden content/de/guide.xml und content/fr/guide.xml für content/en/guide.xml geschrieben. Für Zielpfade gelten dieselben Regeln wie bei JSON, beschrieben unter Ausgabepfade. Mit targetPath legst du ein abweichendes Layout fest. Eine Datei wird dem ersten Eintrag zugeordnet, dessen Muster sie erfasst. Führe Android-Ressourcen daher in einem eigenen Eintrag mit "format": "android" und wähle für den xml-Eintrag ein Muster, das diese Ressourcen nicht erfasst. Dieselbe Konfiguration funktioniert in der CLI und der GitHub App.
Was übersetzt wird #
Jedes Element, das Text enthält, bildet eine Einheit. Enthält ein Element nur andere Elemente, Kommentare und Whitespace, bildet es keine eigene Einheit. Stattdessen werden seine untergeordneten Elemente gelesen:
<?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>Hier bildet title eine Einheit und p eine weitere. Der Kommentar, id und href werden nicht zur Übersetzung gesendet.
- Inline-Elemente. Text mit eingebetteten Elementen, wie
poben, bildet eine Einheit für den gesamten Satz. Die Inline-Elemente werden dem Modell als Platzhalter übergeben, die es verschieben, aber nicht verändern kann. So kann die ÜbersetzungSyncundfilesdort platzieren, wo die Zielsprache sie benötigt. Kommentare und Verarbeitungsanweisungen innerhalb solcher Texte bleiben auf dieselbe Weise erhalten. - Whitespace. Text, der ausschließlich aus Whitespace besteht, etwa die Einrückung zwischen Elementen, wird nie gesendet. Whitespace um den Text bleibt in der Datei erhalten; Whitespace innerhalb des Textes wird unverändert gesendet. Whitespace, den die Übersetzung um ihren Text herum hinzufügt, wird entfernt.
- CDATA. Text, der aus einem einzigen CDATA-Abschnitt besteht, wird übersetzt und wieder als CDATA-Abschnitt geschrieben. Steht ein CDATA-Abschnitt neben anderem Text, wird er Teil dieses Textes und mit Escape-Sequenzen zurückgeschrieben. XML interpretiert beide Schreibweisen gleich.
- Referenzen.
&,<,>,",'und Zeichenreferenzen wie©werden vor der Übersetzung dekodiert. Eine im DOCTYPE deklarierte Entität wie&brand;oder&product-name;wird wie ein Platzhalter geschützt und unverändert zurückgeschrieben. - Werte, die kein Fließtext sind. Text, der ausschließlich aus Ziffern, einer URL, einem ISO-Datum oder einem 22 Zeichen langen Bezeichner aus Buchstaben und Ziffern besteht, wird unverändert in jede Zieldatei kopiert, statt übersetzt zu werden.
Elementnamen und Pfade werden exakt so gelesen, wie sie geschrieben sind – einschließlich Groß- und Kleinschreibung sowie Namensraumpräfixen.
Attribute übersetzen #
Attributwerte werden nur übersetzt, wenn translateComponentProps sie ausdrücklich angibt. Eine Zeichenfolge benennt ein Attribut auf allen Elementen; ein Objekt mit component benennt es nur auf den angegebenen Elementen:
{
"pattern": "content/en/*.xml",
"format": "xml",
"translateComponentProps": ["title", { "component": "item", "props": ["label"] }]
}Damit werden alle title-Attribute sowie das label-Attribut der <item>-Elemente übersetzt. Entscheidend ist die exakte Schreibweise der Namen: x:title und Title sind daher andere Attribute. Leere Werte werden übersprungen. Bezeichner, Links, xml:lang und Namensraumdeklarationen werden nur übersetzt, wenn du sie angibst. Gibst du eines davon versehentlich an, ändert sich dadurch, wie die Datei gelesen wird.
So werden Übersetzungen geschrieben #
In übersetztem Text werden &, < und > durch Escape-Sequenzen ersetzt. In einem übersetzten Attribut gilt das für &, < und das Anführungszeichen, das den Attributwert begrenzt. Tabulatoren und Zeilenumbrüche werden als Zeichenreferenzen geschrieben, damit XML sie beibehält. Ein ]]> in einem übersetzten CDATA-Abschnitt wird auf zwei Abschnitte aufgeteilt. Zeilenumbrüche in einer Übersetzung werden im Zeilenendeformat der Datei geschrieben. Steuerzeichen, die in XML nicht zulässig sind, werden aus der Übersetzung entfernt.
Gibt die Deklaration eine andere Kodierung als UTF-8 an, etwa encoding="ISO-8859-1", werden Nicht-ASCII-Zeichen in der Übersetzung als Zeichenreferenzen geschrieben, etwa é für é. So bleibt die Zieldatei in dieser Kodierung lesbar. Die Datei wird als UTF-8 gelesen. Deklariert sie eine andere Kodierung und enthält sie Rohbytes für Buchstaben mit Akzenten, schlägt die Verarbeitung fehl. Dabei wird die Position des ersten solchen Bytes angegeben, und für diese Datei wird nichts geschrieben. Speichere sie als UTF-8 oder schreibe diese Zeichen als Referenzen.
Der Handler ändert weder xml:lang noch andere Attribute, die die Sprache des Dokuments angeben. Aktualisiere das Attribut in deinem Build oder gib es in translateComponentProps an, wenn es Text enthält.
Schlüssel und Wiederverwendung #
Jede Einheit erhält ihren Elementpfad als Schlüssel, in XPath-Schreibweise: /help/topic/title, /list/item[2] oder /menu/item[1]/@label für ein Attribut. Eine Positionsangabe erscheint nur, wenn ein Element gleichnamige Geschwisterelemente hat. Diese Schlüssel identifizieren die Einheiten im Auftrag und in Studio.
Eine Einheit behält ihre bisherige Übersetzung, solange sich ihr Text und ihr Elementpfad (ohne Positionsangaben) seit dem letzten Push nicht geändert haben und die Übersetzung die Inline-Elemente des Quelltexts mit derselben Verschachtelung beibehält. Die Elemente können in der Übersetzung anders angeordnet sein, da die Wortstellung der Zielsprache dies häufig erfordert. Ein übersetztes Attribut eines Inline-Elements wird zusammen mit dem Element verschoben. Wird ein Element eingefügt, wird nur das neue Element übersetzt. Die nachfolgenden Elemente behalten ihre Übersetzungen, auch wenn sich ihre Positionen geändert haben. Stimmen die Inline-Elemente einer Übersetzung nicht mehr mit denen des Quelltexts überein – etwa weil jemand in der Übersetzung ein Element entfernt oder in ein anderes verschoben hat –, wird die Übersetzung erneut erstellt.
Nicht anwendbare Optionen #
XML hat keine Schlüsselregeln. Die CLI und die GitHub App lehnen einen xml-Eintrag ab, der lockedKeys, preservedKeys, ignoredKeys, keyColumn, injectLocale oder translateFrontmatterFields festlegt. Andernfalls würde die Datei so übersetzt, als wäre die Option nicht gesetzt. lockedPatterns wird ebenfalls abgelehnt, wie bei allen Formaten außer Java properties.
lingo push --key überspringt xml-Dateien mit einer Meldung und führt einen Push für die übrigen ausgewählten Dateien durch.
Ungültiges XML #
Enthält eine Datei kein wohlgeformtes XML, schlägt die Verarbeitung fehl. Die Fehlermeldung nennt Zeile und Spalte des ersten Problems, etwa bei einem nicht geschlossenen oder nicht passenden Tag, einem alleinstehenden &, zwei Wurzelelementen oder Text außerhalb des Wurzelelements. Sind am Dateiende noch mehrere Tags offen, nennt die Fehlermeldung stattdessen diese Tags. Auch bei einer Verschachtelungstiefe von mehr als 256 Elementen schlägt die Verarbeitung fehl. Für diese Datei wird nichts geschrieben; eine vorhandene Zieldatei bleibt unverändert. Ist eine Zieldatei nicht wohlgeformt, schlägt die Verarbeitung auf dieselbe Weise fehl und nennt zusätzlich ihre Sprache. Korrigiere das XML und führe dann erneut einen Push durch.