JSON
Traduce valores de texto anidados y controla qué rutas se copian, conservan, omiten o actualizan.
En un catálogo JSON, la aplicación busca una clave y muestra su valor. El controlador de archivos json modifica los valores de texto y conserva como datos las claves de los objetos, las posiciones de los arreglos, los números, los booleanos y los valores nulos. Reconstruye el destino a partir del origen actual e inserta traducciones nuevas o texto conservado del destino.
El controlador admite catálogos de objetos y arreglos anidados, así como una cadena de texto en la raíz. La CLI infiere json a partir de .json. Configura el origen mediante la configuración de la CLI o la GitHub App.
Qué se convierte en una tarea de traducción #
Por ejemplo:
{
"checkout": {
"title": "Complete your order",
"delivery": "Delivery within {days} days"
},
"plans": [
{ "name": "Personal", "seats": 1 },
{ "name": "Team", "seats": 10 }
],
"enabled": true
}El controlador selecciona checkout.title, checkout.delivery, plans[0].name y plans[1].name. Deja sin cambios los números de seats y el booleano de enabled. Protege explícitamente los identificadores con valores de texto: el tipo JSON de un valor le indica al controlador que es texto, pero no si está destinado a la lectura de las personas.
El formato abreviado de las rutas usa puntos para recorrer objetos y corchetes para indicar posiciones en los arreglos: checkout.title selecciona un valor anidado y plans[0].name selecciona el nombre del primer plan. Para una clave literal llamada checkout.title, usa el formato JSONPath con comillas $['checkout.title']. Consulta los controles de claves para conocer la sintaxis de selección.
Cómo se reutilizan las traducciones existentes en las actualizaciones #
Una ejecución incremental usa tres entradas distintas:
| Entrada | Función |
|---|---|
| Origen actual | Define la estructura y las cadenas de texto de la nueva salida. |
| Origen anterior | Permite determinar si cambió una cadena de texto del origen en la misma ruta. |
| Destino existente | Proporciona traducciones que se pueden conservar. |
Cuando el origen anterior y el destino existente están disponibles, cada cadena de texto nueva o modificada del origen se convierte en una tarea de traducción. Si una cadena del origen no cambió, se puede reutilizar el valor del destino existente en la ruta correspondiente. Dos claves con el mismo texto en inglés siguen siendo registros independientes; pueden tener traducciones aceptadas diferentes porque sus contextos son distintos.
Por ejemplo, cambiar checkout.title no exige por sí solo volver a traducir checkout.delivery. Si el valor de origen de este último no cambió y su valor de destino está disponible, se puede conservar ese valor de destino. Un cambio en un número u otro dato estructural puede requerir reconstruir el archivo, incluso si no hay cadenas de texto nuevas para traducir.
Conserva el origen anterior junto con el destino aceptado que le corresponde. Si falta alguno de los dos, el controlador procesa las cadenas de texto como si fuera la primera ejecución. El Lockfile y la caché de la CLI vinculan esas entradas entre ejecuciones.
Elige qué ocurre con las rutas protegidas #
Estos controles tienen distintos efectos en la salida:
| Control | Comportamiento de traducción | Comportamiento de salida |
|---|---|---|
| Ruta bloqueada | Se excluye de la traducción. | Toma el valor del origen actual. |
| Ruta conservada | Se excluye de la traducción. | Mantiene el valor del destino existente si la ruta existe allí; de lo contrario, conserva el valor del origen. |
| Ruta ignorada | Se excluye de la traducción. | Elimina la ruta del destino generado. |
| Inyección de idioma | El campo de idioma configurado se excluye de la traducción. | Escribe el idioma de destino en ese campo. |
Bloquea un identificador compartido cuando todos los idiomas deban usar el valor del origen. Conserva una URL específica del destino cuando cada idioma tenga su propia URL de destino. Ignora una nota exclusiva del origen cuando no deba aparecer en el archivo traducido. Estas opciones no son sinónimos de “no traducir”.
En una misma ruta, el bloqueo tiene prioridad sobre la conservación, por lo que un valor incluido en ambas listas se toma del origen. Ignorar un valor lo elimina, incluso si también está bloqueado, conservado o seleccionado para la inyección de idioma. El idioma inyectado tiene prioridad sobre el bloqueo y la conservación en esa ubicación. Procura asignar un solo control a cada valor y revisa la salida cuando las reglas se superpongan en un objeto o arreglo.
Eliminar un elemento de un arreglo desplaza las posiciones de los elementos posteriores. Revisa el arreglo resultante como datos, no solo como texto traducido. La inyección de idioma puede crear contenedores de objetos que falten. Al escribir en un arreglo, usa un elemento existente o la posición inmediatamente posterior al final; si una ruta deja huecos o atraviesa un valor incompatible, la operación falla.
Configura estos controles con los campos de las entradas de archivo de la CLI o las opciones de las entradas de archivo de GitHub.
Límites del alcance y la reconstrucción #
Una actualización de claves integra las traducciones seleccionadas en el destino existente. Se mantienen los valores de destino no seleccionados, las claves exclusivas del destino y las omisiones; no se agregan las claves exclusivas del origen que quedan fuera del alcance. Las escrituras en arreglos no deben dejar huecos. Por ejemplo, seleccionar el segundo elemento de un arreglo no rellena automáticamente el primero si está ausente. Revisa el destino completo después de una actualización parcial.
La salida JSON se serializa con una sangría de dos espacios y un salto de línea al final. No esperes que los espacios en blanco o los comentarios se conserven byte por byte. Para archivos de origen con comentarios, consulta JSONC y verifica los requisitos del sistema que los utiliza antes de considerar que un archivo reescrito es equivalente.
El flujo de trabajo de traducción verifica los marcadores de posición compatibles y la estructura ICU, incluidos los argumentos modificados o faltantes. Revisa las advertencias o los errores indicados y luego renderiza la plantilla aceptada con los valores de la aplicación. Estas verificaciones no evalúan si el mensaje traducido expresa el significado previsto.
Carga la salida en la aplicación con valores representativos. Verifica que las rutas protegidas conserven los datos de origen o destino previstos y que el mensaje de entrega siga expresando la misma promesa después de sustituir los valores. El análisis sintáctico verifica la sintaxis JSON; el renderizado y la lectura verifican el mensaje que reciben las personas.