XML

Traduza o texto de qualquer documento XML no próprio ficheiro, preservando a declaração, os comentários, os atributos e a disposição, byte a byte.

O processador de ficheiros xml traduz o texto de documentos XML que não sejam abrangidos por um formato específico, como exportações de conteúdo, ficheiros de ajuda ou formatos de recursos personalizados. Escreve cada tradução numa cópia do ficheiro de origem, mantendo intactos a declaração, o DOCTYPE, os comentários, as instruções de processamento, os atributos, os espaços de nomes e os espaços em branco. Só mudam o texto traduzido e os atributos que indicar.

Os recursos Android, os ficheiros XLIFF e os dicionários de plurais da Apple também são XML, mas têm formatos próprios: Android, XLIFF e Apple stringsdict. Utilize os formatos correspondentes para estes ficheiros, pois reconhecem as chaves, os plurais e o estado de cada tradução.

Configurar a tradução de XML #

Um ficheiro só é traduzido como XML genérico quando a respetiva entrada de ficheiros define "format": "xml". A extensão .xml, por si só, não seleciona nenhum formato, porque um strings.xml do Android utiliza a mesma extensão. Se a entrada de um ficheiro .xml não indicar um formato, a CLI ignora-o e apresenta uma mensagem; a GitHub App também o ignora:

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

Esta configuração escreve content/de/guide.xml e content/fr/guide.xml para content/en/guide.xml. Os caminhos de destino seguem as mesmas regras que os de JSON, descritas em caminhos de saída, e targetPath permite declarar qualquer outra estrutura. Um ficheiro pertence à primeira entrada cujo padrão o selecione. Por isso, mantenha os recursos Android numa entrada própria com "format": "android" e atribua à entrada xml um padrão que não os abranja. A mesma configuração funciona na CLI e na GitHub App.

O que é traduzido #

Cada elemento que contém texto constitui uma unidade. Um elemento que contém apenas outros elementos, comentários e espaços em branco não tem uma unidade própria; nesse caso, são lidos os seus elementos filhos:

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>

Aqui, title é uma unidade e p é outra. O comentário, o id e o href não são enviados para tradução.

  • Elementos em linha. O texto que contém elementos, como o p acima, constitui uma única unidade para toda a frase. Os elementos em linha são enviados ao modelo como marcadores de posição que este pode mover, mas não alterar. Assim, a tradução pode colocar Sync e files onde o idioma de destino o exigir. Os comentários e as instruções de processamento dentro desse texto são preservados da mesma forma.
  • Espaços em branco. O texto composto apenas por espaços em branco, como a indentação entre elementos, nunca é enviado. Os espaços em branco em redor do texto mantêm-se no ficheiro e os que estão no seu interior são enviados sem alterações. Quaisquer espaços em branco acrescentados pela tradução em redor do texto são removidos.
  • CDATA. O texto que consiste numa única secção CDATA é traduzido e gravado como uma secção CDATA. Uma secção CDATA junto de outro texto passa a fazer parte desse texto e é gravada com os devidos caracteres de escape, o que o XML interpreta da mesma forma.
  • Referências. &amp;, &lt;, &gt;, &quot;, &apos; e referências a caracteres como &#169; são descodificados antes da tradução. Uma entidade declarada no DOCTYPE, como &brand; ou &product-name;, é protegida como um marcador de posição e gravada sem alterações.
  • Valores que não são prosa. O texto composto apenas por algarismos, um URL, uma data ISO ou um identificador de 22 caracteres formado por letras e algarismos é copiado para cada destino, em vez de ser traduzido.

Os nomes e os caminhos dos elementos são lidos exatamente como estão escritos, respeitando maiúsculas, minúsculas e prefixos de espaços de nomes.

Traduzir atributos #

Os valores dos atributos só são traduzidos se translateComponentProps os indicar. Uma cadeia de texto indica um atributo em todos os elementos; um objeto com component indica-o apenas nesses elementos:

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

Esta configuração traduz todos os atributos title e o atributo label dos elementos <item>. Os nomes têm de corresponder exatamente à forma como estão escritos, pelo que x:title e Title são atributos distintos. Os valores vazios são ignorados. Os identificadores, as ligações, xml:lang e as declarações de espaços de nomes só são traduzidos se os indicar. Por isso, indicar um deles por engano altera a forma como o ficheiro é lido.

Como são escritas as traduções #

No texto traduzido, &, < e > são escritos com os devidos caracteres de escape. Num atributo traduzido, o mesmo acontece com &, < e o caráter de aspas que delimita o atributo. As tabulações e as quebras de linha são escritas como referências a caracteres para que o XML as preserve. Um ]]> numa secção CDATA traduzida é dividido entre duas secções. As quebras de linha de uma tradução usam a sequência de fim de linha do próprio ficheiro. Os caracteres de controlo que o XML não admite são removidos da tradução.

Quando a declaração indica uma codificação diferente de UTF-8, como encoding="ISO-8859-1", os caracteres não ASCII de uma tradução são escritos como referências a caracteres, como &#xE9; para é, para que o ficheiro de destino continue legível nessa codificação. O ficheiro é lido como UTF-8. Por isso, se declarar outra codificação e contiver bytes em bruto de letras acentuadas, ocorre um erro que indica a posição da primeira ocorrência, e nada é escrito para esse ficheiro. Guarde-o como UTF-8 ou escreva esses caracteres como referências.

O processador não altera xml:lang nem qualquer outro atributo que indique o idioma do documento. Atualize-o no seu processo de compilação ou indique-o em translateComponentProps se contiver texto.

Chaves e reutilização #

Cada unidade tem como chave o caminho do seu elemento, escrito à semelhança de XPath: /help/topic/title, /list/item[2] ou /menu/item[1]/@label para um atributo. A posição só é indicada quando um elemento tem elementos irmãos com o mesmo nome. Estas chaves identificam as unidades na tarefa e no Studio.

Uma unidade mantém a tradução existente desde que o seu texto e o caminho do elemento (excluindo as posições) não tenham mudado desde o último envio e que a tradução preserve os elementos em linha do texto de origem com a mesma estrutura de aninhamento. Estes elementos podem surgir noutra ordem na tradução, como muitas vezes exige a ordem das palavras na língua de destino. Um atributo traduzido de um elemento em linha acompanha esse elemento quando este é movido. Ao inserir um elemento, apenas o novo elemento é traduzido; os elementos seguintes mantêm as suas traduções, mesmo que as suas posições tenham mudado. Se os elementos em linha de uma tradução deixarem de corresponder aos do texto de origem — por exemplo, porque alguém removeu um deles ou o moveu para dentro de outro na tradução —, essa tradução é feita novamente.

Opções que não se aplicam #

O XML não tem regras de chaves. A CLI e a GitHub App rejeitam uma entrada xml que defina lockedKeys, preservedKeys, ignoredKeys, keyColumn, injectLocale ou translateFrontmatterFields, pois, caso contrário, o ficheiro seria traduzido como se a opção não estivesse definida. lockedPatterns também é rejeitado, tal como em todos os formatos exceto propriedades Java.

lingo push --key ignora os ficheiros xml, apresenta uma mensagem e envia os restantes ficheiros selecionados.

XML inválido #

Se um ficheiro não contiver XML bem formado, ocorre um erro que indica a linha e a coluna do primeiro problema, como uma etiqueta não fechada ou sem correspondência, um & isolado, dois elementos raiz ou texto fora do elemento raiz. Se ainda houver várias etiquetas abertas no fim do ficheiro, a mensagem de erro identifica essas etiquetas. Um ficheiro com elementos aninhados a mais de 256 níveis de profundidade também provoca um erro. Nada é escrito para esse ficheiro e, se já existir um ficheiro de destino, este mantém-se intacto. Um destino que não esteja bem formado provoca o mesmo tipo de erro, com indicação do respetivo idioma. Corrija o XML e volte a enviar.