JSON

Traduce cadenas de texto anidadas 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 procesador de archivos json modifica las cadenas de texto y mantiene como datos las claves de los objetos, las posiciones de los arrays, los números, los booleanos y los valores nulos. Reconstruye el destino a partir del origen actual e inserta nuevas traducciones o texto conservado del destino.

El procesador admite catálogos con objetos y arrays anidados, así como una cadena de texto en la raíz. La CLI deduce 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:

json
{
  "checkout": {
    "title": "Complete your order",
    "delivery": "Delivery within {days} days"
  },
  "plans": [
    { "name": "Personal", "seats": 1 },
    { "name": "Team", "seats": 10 }
  ],
  "enabled": true
}

El procesador 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 cuyos valores sean cadenas de texto: el tipo JSON de un valor indica al procesador que se trata de texto, no si está pensado para que lo lean las personas.

La notación abreviada de las rutas usa puntos para recorrer objetos y corchetes para indicar posiciones en los arrays: checkout.title selecciona un valor anidado y plans[0].name selecciona el nombre del primer plan. Para una clave cuyo nombre literal sea checkout.title, usa la notación JSONPath con comillas $['checkout.title']. Consulta los controles de claves para conocer la sintaxis de selección.

Cómo se reutilizan las traducciones existentes al actualizar #

Una ejecución incremental utiliza tres entradas distintas:

EntradaFunción
Origen actualDefine la estructura y las cadenas de texto de la nueva salida.
Origen anteriorPermite determinar si ha cambiado una cadena de texto del origen en la ruta correspondiente.
Destino existenteProporciona las traducciones que se pueden conservar.

Cuando están disponibles el origen anterior y el destino existente, cada cadena de texto nueva o modificada en el origen se convierte en una tarea de traducción. Si una cadena del origen no ha cambiado, 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 implica por sí solo que haya que volver a traducir checkout.delivery. Si el valor de origen de este último no ha cambiado 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 hacer necesario reconstruir el archivo, aunque no haya nuevas cadenas de texto que traducir.

Mantén el origen anterior asociado al destino aceptado. Si falta alguno de los dos, el procesador trata 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 efectos distintos en la salida:

ControlEfecto en la traducciónEfecto en la salida
Ruta bloqueadaSe excluye de la traducción.Toma el valor del origen actual.
Ruta conservadaSe excluye de la traducción.Conserva el valor del destino existente si esa ruta existe; de lo contrario, mantiene el valor de origen.
Ruta ignoradaSe excluye de la traducción.Elimina la ruta del destino generado.
Inserción del idiomaEl 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 de origen. Conserva una URL específica del destino cuando cada idioma tenga su propia dirección 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, aunque también esté bloqueado, conservado o seleccionado para insertar el idioma. El idioma insertado tiene prioridad sobre el bloqueo y la conservación en esa ubicación. Procura asignar un único control a cada valor y comprueba la salida cuando las reglas se solapen en un objeto o array.

Eliminar un elemento de un array desplaza las posiciones de los elementos posteriores. Haz una revisión del array resultante como conjunto de datos, no solo como texto traducido. La inserción del idioma puede crear los objetos contenedores que falten. Al escribir en un array, usa un elemento existente o la posición inmediatamente posterior al último elemento; una ruta que cree huecos o atraviese un valor incompatible provocará un error.

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 de 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 añaden las claves exclusivas del origen que queden fuera del alcance. Las operaciones de escritura en arrays no deben crear huecos. Por ejemplo, seleccionar el segundo elemento de un array no rellena automáticamente el primero si falta. Comprueba 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 comprueba los requisitos del sistema que los utiliza antes de considerar equivalente un archivo reescrito.

El flujo de trabajo de traducción comprueba los marcadores de posición admitidos y la estructura ICU, incluidos los argumentos modificados o ausentes. Comprueba las advertencias o los errores notificados y, después, renderiza la plantilla aceptada con los valores de la aplicación. Estas comprobaciones no evalúan si el mensaje traducido expresa el significado previsto.

Carga la salida en la aplicación con valores representativos. Comprueba que las rutas protegidas conserven los datos de origen o destino previstos y que el mensaje de entrega siga transmitiendo la misma promesa tras la sustitución. El análisis sintáctico verifica la sintaxis JSON; el renderizado y la lectura verifican el mensaje que reciben las personas.