XML

Překládejte text libovolného dokumentu XML přímo v souboru a zachovejte jeho deklaraci, komentáře, atributy i rozvržení bajt po bajtu.

Obslužný modul pro soubory xml překládá text dokumentů XML, pro které není k dispozici specializovaný formát, například exportů obsahu, souborů nápovědy nebo vlastních formátů prostředků. Každý překlad zapisuje do kopie zdrojového souboru, takže deklarace, DOCTYPE, komentáře, instrukce pro zpracování, atributy, jmenné prostory i bílé znaky zůstávají beze změny. Mění se pouze přeložený text a atributy, které určíte.

Prostředky Androidu, XLIFF a slovníky množných čísel Apple jsou také XML, mají ale vlastní formáty: Android, XLIFF a Apple stringsdict. Pro tyto soubory používejte příslušné formáty, protože rozumějí klíčům, množným číslům i stavu jednotlivých překladů.

Nastavení překladu XML #

Soubor se překládá jako obecné XML pouze tehdy, když je v příslušné položce seznamu souborů nastaveno "format": "xml". Samotná přípona .xml žádný formát neurčuje, protože ji používá i soubor strings.xml pro Android. CLI soubor .xml, jehož položka neuvádí žádný formát, přeskočí a vypíše zprávu. GitHub App jej také přeskočí:

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

Toto nastavení zapíše content/de/guide.xml a content/fr/guide.xml pro content/en/guide.xml. Cílové cesty se řídí stejnými pravidly jako u JSON, popsanými v části výstupní cesty. Jiné uspořádání lze určit pomocí targetPath. Soubor patří k první položce, jejímuž vzoru odpovídá. Prostředky Androidu proto ponechte v samostatné položce s "format": "android" a položce xml přiřaďte vzor, který je nezahrnuje. Stejná konfigurace funguje v CLI i v GitHub App.

Co se překládá #

Každý element obsahující text tvoří jednu jednotku. Element, který obsahuje pouze další elementy, komentáře a bílé znaky, vlastní jednotku nemá. Místo něj se načítají jeho podřízené elementy:

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>

Zde tvoří title jednu jednotku a p druhou. Komentář, id ani href se k překladu neodesílají.

  • Vložené elementy. Text obsahující elementy, jako je p výše, tvoří jednu jednotku pro celou větu. Vložené elementy se modelu předávají jako zástupné symboly, které může přesouvat, ale nesmí měnit. V překladu tak mohou být Sync a files tam, kde je cílový jazyk potřebuje. Stejně se zachovávají i komentáře a instrukce pro zpracování uvnitř takového textu.
  • Bílé znaky. Text tvořený pouze bílými znaky, například odsazení mezi elementy, se nikdy neodesílá. Bílé znaky kolem textu zůstávají v souboru a bílé znaky uvnitř textu se odesílají beze změny. Bílé znaky přidané kolem textu při překladu se odstraní.
  • CDATA. Text tvořený jedinou sekcí CDATA se přeloží a zapíše zpět jako sekce CDATA. Sekce CDATA sousedící s dalším textem se stane jeho součástí a zapíše se zpět s escapováním, což XML interpretuje stejně.
  • Odkazy. &amp;, &lt;, &gt;, &quot;, &apos; a znakové odkazy, například &#169;, se před překladem dekódují. Entita deklarovaná v DOCTYPE, například &brand; nebo &product-name;, je chráněna jako zástupný symbol a zapisuje se zpět beze změny.
  • Hodnoty, které nejsou běžným textem. Text tvořený pouze číslicemi, adresou URL, datem ve formátu ISO nebo 22znakovým identifikátorem složeným z písmen a číslic se místo překladu zkopíruje do každého cílového souboru.

Názvy elementů a cesty se načítají přesně tak, jak jsou zapsány, včetně velikosti písmen a předpon jmenných prostorů.

Překlad atributů #

Hodnoty atributů se překládají pouze tehdy, když je uvedete v translateComponentProps. Řetězec určuje atribut na všech elementech, zatímco objekt s component jej určuje pouze na uvedených elementech:

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

Toto nastavení přeloží každý atribut title a atribut label u elementů <item>. Názvy se porovnávají přesně podle zápisu, takže x:title a Title označují jiné atributy. Prázdné hodnoty se přeskakují. Identifikátory, odkazy, xml:lang a deklarace jmenných prostorů se překládají pouze tehdy, když je výslovně uvedete. Pokud tedy některou z těchto položek uvedete omylem, změní se způsob čtení souboru.

Jak se překlady zapisují #

V přeloženém textu se escapují &, < a >. V přeloženém atributu se escapují &, < a znak uvozovek, kterým je atribut ohraničen. Tabulátory a zalomení řádků se zapisují jako znakové odkazy, aby je XML zachovalo. Výskyt ]]> v přeložené sekci CDATA se rozdělí mezi dvě sekce. Pro zalomení řádků v překladu se používá stejný typ konců řádků jako v souboru. Řídicí znaky, které XML nemůže obsahovat, se z překladu odstraní.

Pokud deklarace uvádí jiné kódování než UTF-8, například encoding="ISO-8859-1", znaky mimo ASCII se v překladu zapisují jako znakové odkazy, například &#xE9; pro é, aby cílový soubor zůstal v daném kódování čitelný. Soubor se načítá jako UTF-8. Pokud tedy deklaruje jiné kódování a obsahuje přímo bajty písmen s diakritikou, zpracování selže s uvedením pozice prvního takového znaku a pro soubor se nic nezapíše. Uložte jej v UTF-8 nebo tyto znaky zapište jako odkazy.

Obslužný modul nemění xml:lang ani žádný jiný atribut určující jazyk dokumentu. Aktualizujte jej při sestavení, nebo jej uveďte v translateComponentProps, pokud obsahuje text.

Klíče a opětovné použití překladů #

Klíčem každé jednotky je cesta k jejímu elementu zapsaná podobně jako XPath: /help/topic/title, /list/item[2] nebo /menu/item[1]/@label pro atribut. Pozice se uvádí pouze tam, kde má element sourozenecké elementy se stejným názvem. Tyto klíče identifikují jednotky v úloze i v prostředí Studio.

Jednotka si zachová stávající překlad, pokud se od posledního odeslání nezměnil její text ani cesta k prvku (bez ohledu na pozice) a překlad zachovává vložené prvky zdrojového textu se stejnou strukturou vnoření. Jejich pořadí se v překladu může lišit, jak to často vyžaduje slovosled cílového jazyka. Přeložený atribut vloženého prvku se přesouvá spolu s tímto prvkem. Při vložení nového prvku se přeloží pouze tento prvek; následující prvky si zachovají své překlady, i když se jejich pozice změnily. Pokud vložené prvky v překladu již neodpovídají prvkům zdrojového textu – například proto, že někdo v cílovém textu některý z nich odstranil nebo přesunul dovnitř jiného prvku – překlad se provede znovu.

Volby, které nelze použít #

XML nemá pravidla pro klíče. CLI a GitHub App odmítnou položku xml, ve které je nastaveno lockedKeys, preservedKeys, ignoredKeys, keyColumn, injectLocale nebo translateFrontmatterFields, protože jinak by se soubor přeložil, jako by daná volba nebyla nastavena. lockedPatterns se odmítá stejně jako u všech formátů kromě Java properties.

lingo push --key přeskočí soubory xml, vypíše o tom zprávu a odešle ostatní vybrané soubory.

Neplatné XML #

Zpracování souboru, který není syntakticky správným XML, selže s uvedením řádku a sloupce prvního problému, například neuzavřené či neodpovídající značky, neescapovaného &, dvou kořenových elementů nebo textu mimo kořenový element. Pokud na konci souboru zůstane otevřených několik značek, chybová zpráva místo toho uvede jejich názvy. Zpracování selže také u souboru s elementy vnořenými do více než 256 úrovní. Pro takový soubor se nic nezapíše a existující cílový soubor zůstane beze změny. Zpracování syntakticky nesprávného cílového souboru selže stejným způsobem, přičemž zpráva uvede i jeho jazyk. Opravte XML a poté soubor znovu odešlete.