Archivos de propiedades de Java
Traduce paquetes de recursos .properties de Java una clave a la vez, conservando los comentarios, las líneas en blanco y el formato de cada línea.
Un archivo .properties asocia claves con mensajes, con una entrada por línea, tal como los leen ResourceBundle de Java y MessageSource de Spring. El manejador de archivos properties traduce el valor de cada clave y lo escribe en una copia del archivo de origen. Los comentarios, las líneas en blanco, el orden de las claves, los separadores y el espaciado se conservan intactos. Solo cambia el valor de la clave traducida.
Configurar la traducción de archivos de propiedades #
Un archivo de propiedades solo se incluye en una entrada de archivos cuyo patrón termina en .properties, lo que permite inferir el formato, o que especifica "format": "properties". Una entrada con "format": "properties" selecciona únicamente archivos .properties. Un patrón amplio como src/main/resources/**/* sin ese formato nunca selecciona un archivo de propiedades. Así, los archivos de configuración como application.properties no se traducen por accidente.
Cuando el nombre del archivo contiene el idioma, como en messages_en.properties, cada archivo de destino se guarda junto al de origen, con el idioma de destino en la misma posición del nombre. Los idiomas se escriben con el formato de Java que usa guiones bajos, pt_BR, que es el que busca ResourceBundle:
{
"sourceLocale": "en",
"targetLocales": ["de", "pt-BR"],
"files": [{ "pattern": "src/main/resources/messages_en.properties" }]
}Esto escribe messages_de.properties y messages_pt_BR.properties. Un idioma de origen regional se encuentra de la misma manera: con "sourceLocale": "en-US", el origen es messages_en_US.properties. Configura localeFormat en la entrada para usar otro formato, como "bcp47" para pt-BR. Cuando el origen es el paquete predeterminado, messages.properties, sin idioma en el nombre, declara la ruta de destino:
{
"pattern": "src/main/resources/messages.properties",
"targetPath": "src/main/resources/messages_[locale].properties"
}La misma configuración funciona en la CLI y en la GitHub App.
Cómo se lee el archivo #
Las claves y los valores se leen del mismo modo que los lee java.util.Properties:
- Unidades. Cada clave es una unidad. Si una clave aparece dos veces, se traduce una sola vez con el valor que lee Java: el último. La traducción se escribe en cada aparición de la clave.
- Separadores.
=,:o un espacio en blanco separan una clave de su valor, con espacios opcionales alrededor de=y:. - Comentarios y líneas en blanco. Una línea es un comentario si su primer carácter que no es un espacio en blanco es
#o!. Los comentarios y las líneas en blanco nunca se envían a traducir. - Continuaciones. Una línea que termina en
\continúa en la siguiente, cuyos espacios iniciales se eliminan. Un valor que abarca varias líneas se vuelve a escribir en una sola. - Secuencias de escape.
\uXXXX,\t,\n,\r,\f,\=,\:,\,\\y cualquier otro carácter con escape se decodifican antes de traducirse. Una secuencia de escape\umal formada hace que falle el procesamiento del archivo, al igual que en Java. - Valores vacíos. Una clave cuyo valor está vacío o solo contiene espacios se conserva tal como está y no se traduce. Un valor vacío en un archivo de destino se considera sin traducir, excepto si la clave está en
preservedKeys, en cuyo caso se conserva.
El archivo se lee como UTF-8. No se admiten archivos guardados en ISO-8859-1 con bytes de caracteres acentuados sin escape; guárdalos como UTF-8 o escribe esos caracteres como \uXXXX. La marca de orden de bytes UTF-8 al inicio del archivo no se conserva.
Cómo se escriben las traducciones #
Se aplican secuencias de escape a cada valor traducido para que Java lo vuelva a leer sin cambios: barras invertidas, saltos de línea, tabulaciones, saltos de página y otros caracteres de control, además de un espacio, = o : al inicio. Los caracteres fuera de ASCII se escriben según los valores que ya contiene el archivo. Los comentarios no cuentan:
| Los valores del archivo de destino (o del origen, antes de que exista el primer archivo de destino) | Los caracteres como é o 中 se escriben |
|---|---|
| Ya contienen texto UTF-8 sin escape | Tal como están |
| Contienen solo ASCII | Como \u00E9, \u4E2D |
Cuando se aplican secuencias de escape a los valores, todos los valores escritos las usan, incluso los valores bloqueados o conservados que contienen texto sin escape en el origen. Un archivo con secuencias de escape se carga tanto con un lector UTF-8 como con Properties.load(InputStream), que lee ISO-8859-1.
Los marcadores de posición como {0}, {name} y %s se conservan en la traducción. Las reglas de uso de comillas de MessageFormat de Java, como escribir '' para un apóstrofo en un mensaje con argumentos, no se aplican automáticamente.
Mantener claves y texto sin traducir #
lockedKeys, preservedKeys y ignoredKeys buscan coincidencias con la clave completa, como lo hacía la CLI anterior: un patrón coincide con una clave idéntica a él, con una clave que comienza con el patrón y continúa después de ., / o -, o con una clave que coincide con él como patrón de comodines. Así, app coincide con app.title, app.* coincide con app.title y app.menu.save, y *.port coincide con server.port. En cambio, un patrón que comienza con $ es una consulta JSONPath sobre las claves, como $["app.title"].
| Opción | Resultado en el destino |
|---|---|
lockedKeys | El valor de origen, que nunca se envía a traducir. |
preservedKeys | El valor existente en el destino, o el valor de origen si el destino no tiene uno. |
ignoredKeys | Se omite toda la entrada, incluidas las líneas de continuación. |
lockedPatterns mantiene partes de un valor sin traducir. Cada entrada es una expresión regular en sintaxis RE2, y se bloquean todas las coincidencias dentro de cada valor. ^ y $ coinciden en los saltos de línea dentro de un valor:
{
"pattern": "src/main/resources/messages_en.properties",
"lockedPatterns": ["\\{\\{[^}]+\\}\\}"]
}Cada coincidencia se envía al modelo como un token que debe conservar y se vuelve a escribir byte por byte. Si una traducción pierde o modifica una coincidencia, se rechaza y nunca se escribe. Los patrones buscan coincidencias dentro de cada valor, sin abarcar distintas líneas, claves o comentarios. En un valor con una coincidencia, los marcadores de posición como {0} y %s se protegen de la misma manera.
RE2 se ejecuta en un tiempo proporcional al texto, por lo que no admite aserciones de anticipación o retrospección ((?=, (?!, (?<=, (?<!) ni referencias inversas (\1, \k<name>). Escribe un carácter fuera de ASCII como \x{00E9}, no como \u00E9. La CLI y la GitHub App rechazan los patrones que no sean expresiones regulares al leer la configuración. Si un patrón usa una sintaxis que RE2 no admite, el envío falla e indica el nombre del patrón. lockedPatterns se aplica solo a archivos de propiedades: se rechaza cualquier entrada de otro formato que lo especifique.
--key limita un envío a las claves que especifica, con las mismas reglas de coincidencia que lockedKeys.
Reutilización y correcciones #
Una clave conserva su traducción existente mientras su valor de origen no haya cambiado desde el último envío. Cuando cambia el valor de origen, esa clave se vuelve a traducir. Las claves que solo existen en un archivo de destino se eliminan de él, y las claves de destino siguen el orden y el formato del origen.
En cambio, un envío con --key edita el archivo de destino existente: solo cambian los valores seleccionados. Las demás líneas del destino, incluidas las claves que solo existen en él y sus comentarios, se conservan intactas. Si una clave seleccionada no existe en el destino, se agrega al final.
Para corregir una traducción, edítala en el archivo de destino. Para regenerarla, vuelve a enviarla con --key:
lingo push --key checkout.title --wait