Traducir JSON
Envía un objeto JSON con contexto, indicaciones y rutas protegidas, y luego 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 detalla los campos de la solicitud específicos de JSON.
Enviar un documento directamente en la 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:
{
"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 arreglos anidados. Las cadenas en los nodos hoja son candidatas a traducirse; los números, los valores booleanos y los valores nulos conservan sus tipos JSON. Protege los identificadores, nombres de productos o URL almacenados como cadenas cuando deban permanecer sin cambios.
El contenido de origen enviado directamente en la solicitud usa format.type: "json". Para JSONC u otro formato de archivo, carga los bytes del archivo.
Agregar contexto y seleccionar contenido #
Coloca las opciones de JSON dentro de format.options del documento:
| Opción | Efecto |
|---|---|
context | Texto no vacío que describe el propósito o el público del contenido. |
hints | Consultas JSONPath asociadas a arreglos no vacíos de indicaciones no vacías. Las indicaciones que coinciden se acumulan para las cadenas seleccionadas. El valor predeterminado es un objeto vacío. |
lockedKeys | Copia los valores de origen seleccionados sin traducirlos. El valor predeterminado es []. |
preservedKeys | Reutiliza los valores seleccionados de la versión de destino anterior cuando estén disponibles; de lo contrario, copia los valores de origen. El valor predeterminado es []. |
ignoredKeys | Elimina los valores seleccionados de la salida. El valor predeterminado es []. |
keyScope | Regenera las cadenas seleccionadas mediante una lista no vacía de consultas JSONPath. Requiere una traducción anterior para cada idioma de destino. |
termScope | Regenera las cadenas que coinciden con una lista no vacía de términos de origen. Requiere una traducción anterior para cada idioma de destino. |
injectLocale | Escribe 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 de la 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 arreglo, se incluyen sus cadenas descendientes. Los nombres de 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 alcance no anula estos controles. Consulta la referencia del formato JSON para obtener información sobre cómo se construye 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 regenera toda la cadena seleccionada, no solo el término que coincide. Cuando keyScope y termScope están presentes, la cadena debe cumplir ambos criterios. Usa una selección precisa de claves con JSONPath cuando una subcadena pueda incluir mensajes no relacionados.
Iniciar y leer el resultado #
Guarda el id de la respuesta de creación. Si este trabajo también hace referencia a archivos anteriores u otros documentos, carga cada entrada de uploads y luego 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 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 tardío reemplace contenido más reciente.