XML
Traduce el texto de cualquier documento XML en el propio archivo y conserva su declaración, comentarios, atributos y disposición byte a byte.
El procesador de archivos xml traduce el texto de documentos XML que no cuentan con 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, de modo que la declaración, el DOCTYPE, los comentarios, las instrucciones de procesamiento, los atributos, los espacios de nombres y los espacios en blanco se conservan tal como estaban. 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 cuentan con sus propios formatos: Android, XLIFF y Apple stringsdict. Utiliza 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 solo se traduce como XML genérico si su entrada en la configuración de archivos establece "format": "xml". La extensión .xml por sí sola no selecciona ningún formato, ya que un strings.xml de Android utiliza la misma extensión. La CLI omite los archivos .xml cuya entrada no indique ningún formato y muestra un mensaje; la GitHub App también los omite:
{
"sourceLocale": "en",
"targetLocales": ["de", "fr"],
"files": [{ "pattern": "content/en/*.xml", "format": "xml" }]
}Esta configuración escribe content/de/guide.xml y content/fr/guide.xml para content/en/guide.xml. Las rutas de destino siguen las mismas reglas que las de JSON, descritas en rutas de salida, y targetPath permite definir cualquier otra disposición. Cada archivo pertenece a la primera entrada cuyo patrón lo seleccione, así que mantén los recursos de Android en una entrada independiente 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. Un elemento que solo contiene otros elementos, comentarios y espacios en blanco no tiene una unidad propia; en su lugar, se leen sus elementos secundarios:
<?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
pen el ejemplo anterior, constituye una sola unidad que abarca toda la frase. 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 situarSyncyfilesdonde lo requiera el idioma de destino. Los comentarios y las instrucciones de procesamiento dentro de ese texto se conservan del mismo modo. - 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 hay dentro del texto se envían sin cambios. Se eliminan los espacios en blanco que la traducción añada alrededor del texto.
- CDATA. El texto formado por una única 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 los caracteres escapados, que XML interpreta del mismo modo.
- Referencias.
&,<,>,",'y las referencias a caracteres, como©, 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 tal cual. - 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 nunca se traducen a menos que translateComponentProps los indique. Una cadena especifica un atributo en todos los elementos; un objeto con component lo especifica solo en esos elementos:
{
"pattern": "content/en/*.xml",
"format": "xml",
"translateComponentProps": ["title", { "component": "item", "props": ["label"] }]
}Esta configuración traduce todos los atributos title y el atributo label de los elementos <item>. Los nombres deben coincidir exactamente tal 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 de leer el archivo.
Cómo se escriben las traducciones #
En el texto traducido, se escapan &, < y >. En un atributo traducido, se escapan &, < y el carácter de comillas que utiliza el propio atributo; las tabulaciones y los saltos de línea se escriben como referencias a caracteres para que XML los conserve. Un ]]> en una sección CDATA traducida se divide entre dos secciones. Los saltos de línea de una traducción se escriben con el formato de fin de línea del propio 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 quedan fuera de ASCII se escriben como referencias a caracteres, por ejemplo é para é, de modo que el destino siga siendo legible con esa codificación. El archivo se lee como UTF-8, por lo que, si declara otra codificación y contiene bytes sin procesar correspondientes a letras acentuadas, se produce 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 modifica 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 tiene como clave la ruta de su elemento, escrita como XPath: /help/topic/title, /list/item[2] o /menu/item[1]/@label para un atributo. Solo se incluye una posición cuando un elemento tiene elementos hermanos con el mismo nombre. Estas claves identifican las unidades en el trabajo y en Studio.
Una unidad conserva su traducción actual siempre que su texto y la ruta del elemento (sin tener en cuenta las posiciones) no hayan cambiado desde el último envío y la traducción mantenga los elementos en línea del original con el mismo anidamiento. Estos elementos pueden aparecer en un orden distinto en la traducción, como suele exigir el orden de las palabras en el idioma de destino. Los atributos traducidos de un elemento en línea se desplazan junto con él. Al insertar un elemento, solo se traduce el nuevo; los elementos que le siguen conservan sus traducciones aunque hayan cambiado de posición. Si los elementos en línea de una traducción dejan de coincidir con los del original —por ejemplo, porque alguien ha eliminado uno o lo ha colocado dentro de otro en el texto de destino—, se vuelve a traducir esa unidad.
Opciones que no se aplican #
XML no tiene reglas de claves. La CLI y la GitHub App rechazan las entradas xml que establezcan lockedKeys, preservedKeys, ignoredKeys, keyColumn, injectLocale o translateFrontmatterFields, ya que, de lo contrario, el archivo se traduciría como si la opción no estuviera configurada. lockedPatterns también se rechaza, como en todos los formatos salvo propiedades de Java.
lingo push --key omite los archivos xml y muestra un mensaje, y envía los demás archivos seleccionados.
XML no válido #
Un archivo XML que no esté bien formado produce 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 al final del archivo quedan varias etiquetas abiertas, el error las identifica en su lugar. También se produce un error si los elementos del archivo superan los 256 niveles de anidamiento. No se escribe nada para ese archivo y, si ya existe un destino, se conserva tal como está. Un destino que no esté bien formado produce el mismo error, con indicación de su idioma. Corrige el XML y vuelve a enviarlo.