XML

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

O processador de arquivos xml traduz o texto de documentos XML que não são cobertos por um formato específico, como exportações de conteúdo, arquivos de ajuda ou formatos de recursos personalizados. Cada tradução é gravada em uma cópia do arquivo de origem, preservando a declaração, o DOCTYPE, os comentários, as instruções de processamento, os atributos, os namespaces e os espaços em branco. Só mudam o texto traduzido e os atributos que você especificar.

Os recursos do Android, o 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. Use esses formatos para os respectivos arquivos, pois eles reconhecem as chaves, os plurais e o estado de cada tradução.

Configurar a tradução de XML #

Um arquivo só é traduzido como XML genérico quando sua entrada na configuração de arquivos define "format": "xml". A extensão .xml, por si só, não seleciona nenhum formato, pois um strings.xml do Android usa a mesma extensão. A CLI ignora arquivos .xml cuja entrada não especifica um formato e exibe uma mensagem; o GitHub App também os ignora:

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

Isso grava content/de/guide.xml e content/fr/guide.xml para content/en/guide.xml. Os caminhos de destino seguem as mesmas regras do JSON, descritas em caminhos de saída, e targetPath permite declarar outras estruturas. Um arquivo pertence à primeira entrada cujo padrão o seleciona. Por isso, mantenha os recursos do Android em uma entrada própria com "format": "android" e use, na entrada xml, um padrão que não os inclua. A mesma configuração funciona na CLI e no GitHub App.

O que é traduzido #

Cada elemento que contém texto forma 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, seus elementos filhos são lidos:

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. Um texto que contém elementos, como o p acima, forma uma única unidade para a frase inteira. Os elementos em linha são enviados ao modelo como marcadores de posição que ele pode mover, mas não alterar. Assim, a tradução pode posicionar Sync e files conforme o idioma de destino exigir. Comentários e instruções de processamento dentro desse texto são preservados da mesma forma.
  • Espaços em branco. Textos compostos apenas por espaços em branco, como a indentação entre elementos, nunca são enviados. Os espaços em branco ao redor do texto permanecem no arquivo, e os espaços em branco dentro dele são enviados sem alterações. Espaços em branco adicionados pela tradução ao redor do texto são descartados.
  • CDATA. Um texto composto por uma única seção CDATA é traduzido e gravado novamente como uma seção CDATA. Uma seção CDATA junto de outro texto passa a fazer parte desse texto e é gravada com escape, o que o XML interpreta da mesma forma.
  • Referências. &amp;, &lt;, &gt;, &quot;, &apos; e referências de caracteres, como &#169;, são decodificadas 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. Textos compostos apenas por dígitos, uma URL, uma data ISO ou um identificador de 22 caracteres formado por letras e dígitos são copiados para cada destino, em vez de serem traduzidos.

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

Traduzir atributos #

Os valores dos atributos só são traduzidos quando translateComponentProps os especifica. Uma string especifica um atributo em todos os elementos; um objeto com component o especifica apenas nos elementos indicados:

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

Isso traduz todos os atributos title e o atributo label dos elementos <item>. Os nomes precisam corresponder exatamente ao que está escrito; portanto, x:title e Title são atributos diferentes. Valores em branco são ignorados. Identificadores, links, xml:lang e declarações de namespace só são traduzidos se você os especificar. Por isso, especificar um deles por engano altera a forma como o arquivo é lido.

Como as traduções são gravadas #

No texto traduzido, &, < e > são gravados com escape. Em um atributo traduzido, &, < e o caractere de aspas usado no próprio atributo são gravados com escape, e tabulações e quebras de linha são gravadas como referências de caracteres para que o XML as preserve. Um ]]> em uma seção CDATA traduzida é dividido entre duas seções. As quebras de linha da tradução seguem o padrão de fim de linha do próprio arquivo. Caracteres de controle que o XML não aceita são descartados da tradução.

Quando a declaração especifica uma codificação diferente de UTF-8, como encoding="ISO-8859-1", os caracteres da tradução que estão fora do conjunto ASCII são gravados como referências de caracteres, como &#xE9; para é, para que o destino continue legível nessa codificação. O arquivo é lido como UTF-8. Por isso, um arquivo que declara outra codificação e contém bytes brutos de letras acentuadas gera um erro que indica a posição da primeira delas, e nada é gravado para esse arquivo. Salve-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 esse atributo durante a compilação ou especifique-o em translateComponentProps se ele contiver texto.

Chaves e reutilização #

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

Uma unidade mantém a tradução existente desde que seu texto e o caminho do elemento (sem considerar 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 o mesmo aninhamento. Esses elementos podem aparecer em outra ordem na tradução, como muitas vezes exige a ordem das palavras no idioma de destino. Um atributo traduzido de um elemento em linha acompanha esse elemento quando ele é movido. Ao inserir um elemento, apenas o novo elemento é traduzido; os elementos seguintes mantêm suas traduções, mesmo que 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 no texto de destino —, ela será traduzida novamente.

Opções que não se aplicam #

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

lingo push --key ignora os arquivos xml, exibe uma mensagem e envia os outros arquivos selecionados.

XML inválido #

Um arquivo XML malformado gera um erro que indica a linha e a coluna do primeiro problema, como uma tag não fechada ou sem correspondência, um & sem escape, dois elementos raiz ou texto fora do elemento raiz. Se várias tags ainda estiverem abertas no fim do arquivo, o erro informa os nomes delas. Um arquivo com mais de 256 níveis de aninhamento de elementos também gera um erro. Nada é gravado para esse arquivo, e um destino existente permanece como está. Um destino malformado gera um erro da mesma forma, com a indicação do idioma. Corrija o XML e envie novamente.