XML

Traduce el texto de cualquier documento XML en su lugar y conserva su declaración, comentarios, atributos y distribución byte por byte.

El procesador de archivos xml traduce el texto de documentos XML para los que no hay un formato específico, como una exportación de contenido, un archivo de ayuda o un formato de recursos personalizado. Escribe cada traducción en una copia del archivo de origen, por lo que la declaración, el DOCTYPE, los comentarios, las instrucciones de procesamiento, los atributos, los espacios de nombres y los espacios en blanco quedan intactos. Solo cambian el texto traducido y los atributos que indiques.

Los recursos de Android, XLIFF y los diccionarios de plurales de Apple también son XML, pero tienen sus propios formatos: Android, XLIFF y stringsdict de Apple. Usa esos formatos para estos archivos, ya que reconocen las claves, los plurales y el estado de cada traducción.

Configurar la traducción de XML #

Un archivo se traduce como XML genérico solo cuando su entrada en la configuración de archivos establece "format": "xml". La extensión .xml por sí sola no selecciona ningún formato, porque un strings.xml de Android usa la misma extensión. Si la entrada de un archivo .xml no indica ningún formato, la CLI lo omite y muestra un mensaje; la GitHub App también lo omite:

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

Esto escribe content/de/guide.xml y content/fr/guide.xml para content/en/guide.xml. Las rutas de destino siguen las mismas reglas que JSON, descritas en rutas de salida, y targetPath permite declarar cualquier otra estructura. Un archivo pertenece a la primera entrada cuyo patrón lo selecciona, así que mantén los recursos de Android en su propia entrada con "format": "android" y asigna a la entrada xml un patrón que no los incluya. La misma configuración funciona en la CLI y en la GitHub App.

Qué se traduce #

Cada elemento que contiene texto constituye una unidad. Si un elemento solo contiene otros elementos, comentarios y espacios en blanco, no tiene una unidad propia; en su lugar, se leen sus elementos secundarios:

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>

Aquí, title es una unidad y p es otra. El comentario, id y href no se envían a traducir.

  • Elementos en línea. El texto que contiene elementos, como p en el ejemplo anterior, forma una sola unidad que abarca toda la oración. Los elementos en línea se envían al modelo como marcadores de posición que puede mover, pero no modificar. Así, la traducción puede colocar Sync y files donde lo requiera el idioma de destino. Los comentarios y las instrucciones de procesamiento dentro de ese texto se conservan de la misma manera.
  • Espacios en blanco. El texto compuesto únicamente por espacios en blanco, como la sangría entre elementos, nunca se envía. Los espacios en blanco que rodean el texto se conservan en el archivo, y los que están dentro de él se envían sin cambios. Se eliminan los espacios en blanco que la traducción agregue alrededor de su texto.
  • CDATA. El texto formado por una sola sección CDATA se traduce y se vuelve a escribir como una sección CDATA. Una sección CDATA junto a otro texto pasa a formar parte de ese texto y se vuelve a escribir con caracteres de escape, que XML interpreta de la misma manera.
  • Referencias. &amp;, &lt;, &gt;, &quot;, &apos; y las referencias de caracteres como &#169; se decodifican antes de la traducción. Una entidad declarada en el DOCTYPE, como &brand; o &product-name;, se protege como un marcador de posición y se vuelve a escribir sin cambios.
  • Valores que no son prosa. El texto compuesto únicamente por dígitos, una URL, una fecha ISO o un identificador de 22 caracteres formado por letras y dígitos se copia en cada destino en lugar de traducirse.

Los nombres y las rutas de los elementos se leen exactamente como están escritos, respetando las mayúsculas, las minúsculas y los prefijos de espacios de nombres.

Traducir atributos #

Los valores de los atributos solo se traducen si translateComponentProps los indica. Una cadena especifica un atributo en todos los elementos; un objeto con component lo especifica solo en esos elementos:

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

Esto traduce todos los atributos title y el atributo label de los elementos <item>. Los nombres deben coincidir exactamente como están escritos, por lo que x:title y Title son atributos distintos. Los valores vacíos se omiten. Los identificadores, los enlaces, xml:lang y las declaraciones de espacios de nombres solo se traducen si los indicas, así que especificar uno por error cambia la forma en que se lee el archivo.

Cómo se escriben las traducciones #

En el texto traducido, &, < y > se escriben con caracteres de escape. En un atributo traducido, lo mismo ocurre con &, < y el carácter de comillas que delimita el atributo. Además, las tabulaciones y los saltos de línea se escriben como referencias de caracteres para que XML los conserve. Un ]]> en una sección CDATA traducida se divide entre dos secciones. Los saltos de línea de la traducción se escriben con el mismo tipo de fin de línea que usa el archivo. Los caracteres de control que XML no admite se eliminan de la traducción.

Cuando la declaración indica una codificación distinta de UTF-8, como encoding="ISO-8859-1", los caracteres de la traducción que no pertenecen a ASCII se escriben como referencias de caracteres, por ejemplo, &#xE9; para é. Así, el archivo de destino sigue siendo legible en esa codificación. El archivo se lee como UTF-8, por lo que, si declara otra codificación y contiene bytes sin procesar de letras acentuadas, se genera un error que indica la posición de la primera de ellas y no se escribe nada para ese archivo. Guárdalo como UTF-8 o escribe esos caracteres como referencias.

El procesador no cambia xml:lang ni ningún otro atributo que indique el idioma del documento. Actualízalo durante la compilación o indícalo en translateComponentProps si contiene texto.

Claves y reutilización #

Cada unidad usa como clave la ruta de su elemento, escrita como XPath: /help/topic/title, /list/item[2] o /menu/item[1]/@label para un atributo. La posición solo se indica cuando un elemento tiene elementos hermanos con el mismo nombre. Estas claves identifican las unidades en la tarea y en Studio.

Una unidad conserva su traducción actual siempre que su texto y la ruta del elemento (sin contar las posiciones) no hayan cambiado desde el último envío y que la traducción mantenga los elementos en línea del texto fuente con el mismo anidamiento. La traducción puede ordenarlos de otra manera, como suele exigir el orden de las palabras en el idioma de destino. Los atributos traducidos de un elemento en línea se mueven junto con ese elemento. Al insertar un elemento, solo se traduce el nuevo; los elementos que le siguen conservan sus traducciones aunque sus posiciones hayan cambiado. Si los elementos en línea de una traducción ya no coinciden con los del texto fuente —por ejemplo, porque alguien eliminó uno o lo movió dentro de otro en el texto de destino—, se vuelve a traducir.

Opciones que no se aplican #

XML no tiene reglas de claves. La CLI y la GitHub App rechazan cualquier entrada xml que establezca lockedKeys, preservedKeys, ignoredKeys, keyColumn, injectLocale o translateFrontmatterFields, porque, de lo contrario, el archivo se traduciría como si la opción no estuviera configurada. lockedPatterns también se rechaza, como ocurre con todos los formatos excepto propiedades de Java.

lingo push --key omite los archivos xml, muestra un mensaje y envía los demás archivos seleccionados.

XML no válido #

Un archivo XML que no esté bien formado genera un error que indica la línea y la columna del primer problema, como una etiqueta sin cerrar o que no coincide, un & sin escapar, dos elementos raíz o texto fuera del elemento raíz. Si varias etiquetas siguen abiertas al final del archivo, el error indica cuáles son. Un archivo con más de 256 niveles de anidamiento también genera un error. No se escribe nada para ese archivo y, si ya existe un archivo de destino, queda intacto. Un archivo de destino que no esté bien formado genera el mismo tipo de error, que también indica su idioma. Corrige el XML y vuelve a enviarlo.