Traducir JSON

Envía un objeto JSON con contexto, indicaciones y rutas protegidas y descarga sus traducciones.

Envía un objeto JSON directamente en un trabajo de localización cuando tu aplicación ya tenga el contenido de origen en memoria. Lingo.dev lo guarda como un documento JSON y genera una salida para cada idioma de destino.

La guía de inicio rápido incluye un programa completo. Esta referencia explica los campos de la solicitud específicos de JSON.

Enviar un documento en la propia solicitud #

Crea el trabajo en POST /v2/organizations/:orgId/localization/jobs con una clave de API en X-API-Key y un Idempotency-Key estable para este envío:

json
{
  "engineId": "YOUR_ENGINE_ID",
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "documents": [
    {
      "key": "settings.json",
      "format": {
        "type": "json",
        "options": {
          "context": "Settings dialog in a team collaboration application",
          "hints": { "$.save": ["Button that saves the edited settings"] },
          "lockedKeys": ["$.productName"]
        }
      },
      "source": {
        "content": {
          "save": "Save changes",
          "cancel": "Cancel",
          "productName": "Acme"
        }
      }
    }
  ]
}

El contenido de origen debe ser un objeto JSON. Puede contener objetos y matrices anidados. Las cadenas de los nodos hoja son candidatas a la traducción; los números, los booleanos y los valores nulos conservan sus tipos JSON. Protege los identificadores, nombres de productos o URL que sean cadenas y deban permanecer sin cambios.

El contenido de origen enviado en la propia solicitud usa format.type: "json". Para JSONC u otro formato de archivo, sube los bytes del archivo.

Añadir contexto y seleccionar contenido #

Incluye las opciones de JSON en el campo format.options del documento:

OpciónEfecto
contextTexto no vacío que describe la finalidad del contenido o el público al que va dirigido.
hintsConsultas JSONPath asociadas a matrices no vacías de indicaciones también no vacías. Las indicaciones que coinciden se acumulan para las cadenas seleccionadas. El valor predeterminado es un objeto vacío.
lockedKeysCopia los valores de origen seleccionados sin traducirlos. El valor predeterminado es [].
preservedKeysReutiliza los valores seleccionados del destino anterior si están disponibles; de lo contrario, copia los valores de origen. El valor predeterminado es [].
ignoredKeysElimina los valores seleccionados de la salida. El valor predeterminado es [].
keyScopeVuelve a generar las cadenas seleccionadas mediante una lista no vacía de consultas JSONPath. Requiere una traducción anterior para cada idioma de destino.
termScopeVuelve a generar las cadenas que coincidan con una lista no vacía de términos de origen. Requiere una traducción anterior para cada idioma de destino.
injectLocaleEscribe el idioma de destino en una única ubicación JSONPath, como $.meta.locale. Ese subárbol queda protegido para que no se traduzca.

Usa JSONPath en las solicitudes a la API. $.title selecciona una propiedad del objeto raíz; $.nav.home selecciona una propiedad anidada; $['nav.home'] selecciona una clave literal que contiene un punto; $..productName selecciona esa propiedad a cualquier profundidad. Al seleccionar un objeto o una matriz, se incluyen las cadenas de sus nodos descendientes. Los nombres de las claves por sí solos no son consultas válidas para la API.

Los controles de las claves se resuelven antes de traducir. Los valores ignorados se eliminan; los valores de origen bloqueados tienen prioridad sobre los valores de destino conservados. La selección del ámbito no anula estos controles. Consulta la referencia del formato JSON para obtener información sobre cómo se compone la salida y sobre los mensajes ICU.

termScope busca coincidencias de subcadenas en las cadenas de origen y distingue entre mayúsculas y minúsculas. Cualquier término de la lista puede seleccionar una cadena: "cat" también coincide con "catalog", mientras que "login" no coincide con "Login". Se vuelve a generar toda la cadena seleccionada, no solo el término coincidente. Si se incluyen tanto keyScope como termScope, la cadena debe cumplir ambas condiciones. Usa una selección precisa de claves con JSONPath cuando una subcadena pueda incluir mensajes no relacionados.

Iniciar y consultar el resultado #

Guarda el id de la respuesta de creación. Si este trabajo también hace referencia a archivos anteriores u otros documentos, sube cada entrada de uploads y, después, llama a POST /v2/localization/jobs/:id/start.

Lee GET /v2/localization/jobs/:id y revisa el targets de cada documento. Un destino con status._tag: "Completed" tiene un status.downloadUrl. Descarga el contenido de esa URL con la misma autenticación para obtener el objeto JSON. La respuesta del trabajo contiene el progreso y las direcciones de los artefactos, no el objeto traducido.

Para las actualizaciones, envía los artefactos de origen y destino anteriores tal como se describe en actualizar un documento existente. Guarda la nueva revisión del contenido de origen junto con el ID del trabajo para evitar que un resultado que llegue con retraso sustituya contenido más reciente.