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:
{
"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 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
pacima, 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 posicionarSyncefilesconforme 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.
&,<,>,",'e referências de caracteres, como©, 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:
{
"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 é 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.