Archivos de propiedades de Java
Traduce los paquetes de recursos .properties de Java clave por clave, 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 gestor 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 los espacios se mantienen intactos. Solo cambia el valor de la clave traducida.
Configurar la traducción de archivos de propiedades #
Un archivo de propiedades solo puede pertenecer a una entrada de archivos cuyo patrón termine en .properties, en cuyo caso se deduce el formato, o que especifique "format": "properties". Una entrada con "format": "properties" selecciona únicamente archivos .properties. Un patrón amplio como src/main/resources/**/* sin ese formato nunca selecciona archivos de propiedades, lo que evita traducir por accidente archivos de configuración como application.properties.
Cuando el nombre del archivo incluye 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, y que ResourceBundle utiliza para buscarlos:
{
"sourceLocale": "en",
"targetLocales": ["de", "pt-BR"],
"files": [{ "pattern": "src/main/resources/messages_en.properties" }]
}Esto genera messages_de.properties y messages_pt_BR.properties. Un idioma de origen con variante regional se localiza del mismo modo: con "sourceLocale": "en-US", el origen es messages_en_US.properties. Establece localeFormat en la entrada para escribir otro formato, como "bcp47" para pt-BR. Si 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 todas sus apariciones.
- Separadores.
=,:o los espacios 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 distinto de 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 repartido en varias líneas se vuelve a escribir en una sola. - Secuencias de escape.
\uXXXX,\t,\n,\r,\f,\=,\:,\,\\y cualquier otro carácter escapado se descodifican antes de traducir. Una secuencia de escape\umal formada hace que falle el procesamiento del archivo, igual que en Java. - Valores vacíos. Una clave cuyo valor está vacío o solo contiene espacios se conserva tal cual y no se traduce. Un valor vacío en el destino se considera sin traducir, salvo si la clave está en
preservedKeys, que conserva ese valor.
El archivo se lee como UTF-8. No se admiten archivos guardados en ISO-8859-1 con bytes sin escapar para los caracteres acentuados; guárdalos como UTF-8 o escribe esos caracteres como \uXXXX. Si el archivo empieza con una marca de orden de bytes UTF-8, esta no se conserva.
Cómo se escriben las traducciones #
Cada valor traducido se escribe con las secuencias de escape necesarias para que Java lo lea sin cambios. Se escapan las barras invertidas, los saltos de línea, las tabulaciones, los saltos de página y otros caracteres de control, así como un espacio, = o : al principio del valor. 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 de origen, antes de que exista el primer archivo de destino) | Los caracteres como é o 中 se escriben |
|---|---|
| Ya contienen texto UTF-8 sin escapar | Tal cual |
| Solo contienen ASCII | Como \u00E9, \u4E2D |
Cuando se usan secuencias de escape, se aplican a todos los valores que se escriben, incluidos los valores bloqueados o conservados que contengan texto sin escapar 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 representar 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 hacía la CLI anterior: un patrón coincide con una clave idéntica a él, con una clave que lo prolonga después de ., / o -, o con una clave que coincide con él como patrón glob. 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 empieza por $ 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 no hay ninguno. |
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 marcador 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, no entre líneas, claves o comentarios. En un valor que contiene una coincidencia, los marcadores de posición como {0} y %s se protegen del mismo modo.
RE2 se ejecuta en un tiempo proporcional a la longitud del texto, por lo que no admite aserciones de anticipación ni de retrospección ((?=, (?!, (?<=, (?<!) ni referencias inversas (\1, \k<name>). Escribe los caracteres fuera de ASCII como \x{00E9}, no como \u00E9. Al leer la configuración, la CLI y la GitHub App rechazan cualquier patrón que no sea una expresión regular. Si un patrón usa una sintaxis que RE2 no admite, el envío falla e indica qué patrón ha causado el error. lockedPatterns solo se aplica a los 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. Si 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 modifica 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 mantienen intactas. Si una clave seleccionada no existe en el destino, se añade 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