Traducir documentos
Carga archivos de origen y traducciones anteriores, inicia un trabajo de localización y descarga los archivos resultantes.
Usa trabajos de traducción de documentos para traducir archivos sin perder su formato. Un trabajo puede incluir varios archivos e idiomas de destino. La API identifica cada archivo mediante el hash SHA-256 de sus bytes exactos.
Necesitas una clave de API, un ID de organización y un ID de motor. La guía de localización de archivos incluye un ejemplo completo en Node.js.
Elige un formato #
Configura format.type en cada documento:
| Formato | Tipo |
|---|---|
| JSON / JSONC | json / jsonc |
| Markdown / MDX / Markdoc | md / mdx / markdoc |
| HTML | html |
| TypeScript / PHP | typescript / php |
| YAML / YAML con raíz de idioma / YAML de OpenAPI | yaml / yaml-root-key / yaml-openapi |
| Android / Flutter ARB | android / flutter |
| Cadenas de Apple / diccionarios de plurales / catálogos de cadenas | xcode-strings / xcode-stringsdict / xcode-xcstrings |
| Gettext / XLIFF / SubRip | po / xliff / srt |
| Texto sin formato | txt |
| Tabla CSV con una columna por idioma | csv |
| Propiedades de Java | properties |
| Contenido de Payload | payload |
Las referencias de formatos explican las estructuras de los archivos y los controles. format.options de la API usa el contrato de documento; la configuración de la CLI adapta sus propios nombres de opciones a este contrato. Por ejemplo, la API usa frontmatterFields para Markdown y componentProps para las propiedades de los componentes. Los selectores de claves JSON usan JSONPath.
Configura las opciones de formato #
Puedes omitir format.options para usar los valores predeterminados. Configura solo las opciones que admite el tipo seleccionado:
| Tipo | Opciones |
|---|---|
json, jsonc | Opciones de JSON: reglas de claves, ámbitos, contexto, indicaciones e inserción del idioma. |
typescript, php, yaml, yaml-root-key | lockedKeys, preservedKeys, ignoredKeys (valor predeterminado: []); keyScope y termScope opcionales, no vacíos. |
md | frontmatterFields (valor predeterminado: ["$.title", "$.description"]); termScope opcional, no vacío. |
mdx, markdoc | Opciones de Markdown más componentProps (valor predeterminado: []). |
html | componentProps (valor predeterminado: []), además de los atributos traducibles integrados en el procesador. |
xcode-stringsdict | lockedKeys y preservedKeys (valor predeterminado: []); termScope opcional, no vacío. |
flutter, xcode-strings, xcode-xcstrings, android, yaml-openapi | termScope opcional, no vacío. |
csv | keyColumn opcional: el encabezado de la columna de claves (valor predeterminado: la primera celda del encabezado). |
properties | lockedKeys, preservedKeys, ignoredKeys (valor predeterminado: []) y keyScope opcional, que no debe estar vacío si se especifica; se comparan con la clave completa como patrones de estilo antiguo o como JSONPath cuando un patrón comienza con $; termScope opcional, que no debe estar vacío si se especifica; lockedPatterns (valor predeterminado: []), expresiones regulares RE2 que se conservan sin traducir en los valores. |
payload, po, xliff, srt, txt | Sin opciones adicionales. |
Las reglas de claves, los ámbitos de claves y los campos de metadatos iniciales usan consultas JSONPath. termScope selecciona unidades de origen completas que contengan cualquiera de los términos proporcionados como subcadena, distinguiendo entre mayúsculas y minúsculas; "cat" puede coincidir con "catalog". Cuando un formato admite tanto keyScope como termScope, proporcionar ambos selecciona su intersección. Ambos ámbitos requieren traducciones existentes en las que integrar los resultados. La selección y la reutilización dependen del formato, como se explica en actualizaciones incrementales. Estas opciones de la API difieren de la compatibilidad de formatos de --key en la CLI.
Una regla de propiedades de componentes contiene props, un arreglo no vacío de nombres de propiedades, y, opcionalmente, components, un arreglo no vacío que limita la regla a los componentes con los nombres indicados. Si omites components, la regla se aplica a cualquier componente. Para MDX:
{
"type": "mdx",
"options": {
"frontmatterFields": ["$.title", "$.description", "$.sidebar.label"],
"componentProps": [{ "components": ["Callout"], "props": ["title"] }]
}
}Esto traduce los metadatos iniciales seleccionados y los títulos literales de Callout, junto con el texto del documento. Consulta la referencia del formato para obtener detalles sobre el código protegido, las expresiones y el comportamiento de reconstrucción.
Crea el trabajo con direcciones de artefactos #
Calcula el hash de los bytes exactos que vas a cargar. En Node.js:
import { createHash } from "node:crypto";
import { readFile } from "node:fs/promises";
const bytes = await readFile("messages/en.json");
const address = createHash("sha256").update(bytes).digest("hex");Crea un trabajo y usa la dirección resultante como source del documento:
{
"engineId": "YOUR_ENGINE_ID",
"sourceLocale": "en",
"targetLocales": ["de"],
"documents": [
{
"key": "messages/en.json",
"format": { "type": "json" },
"source": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
]
}Reemplaza la dirección de ejemplo por el hash calculado. Guarda el ID del trabajo que se devuelve. uploads enumera los artefactos de entrada que faltan en el almacenamiento; no necesitas volver a cargar el contenido que ya está almacenado.
Carga los bytes e inicia el trabajo #
Para cada entrada de uploads, envía una solicitud PUT autenticada a su uploadUrl con Content-Type: application/octet-stream y los bytes originales como cuerpo. Carga los archivos de origen y cualquier archivo anterior al que se haga referencia antes de iniciar el trabajo.
Cada artefacto tiene un límite de 25 MiB. Si el hash no coincide, se devuelve ArtifactChecksumMismatch; si el archivo supera el tamaño permitido, se devuelve RequestBodyTooLarge. Si calculas el hash del texto y luego cambias sus finales de línea antes de cargarlo, los bytes cambian y la verificación falla.
Llama a POST /v2/localization/jobs/:id/start cuando todas las cargas se hayan completado correctamente. Solo se aceptan cargas de artefactos antes de que comience el trabajo. Consulta el progreso de los idiomas de destino del trabajo y luego descarga los archivos completados desde las URL devueltas.
Actualiza un documento existente #
Conserva tres entradas para una actualización incremental: el nuevo archivo de origen, el archivo de origen anterior y la traducción actual de cada idioma de destino. Proporciona:
source: la dirección del artefacto del nuevo archivo de origen.previousSource: la dirección de origen usada para la revisión anterior.previousTranslations: una entrada de{ "locale": "de", "artifact": "..." }por cada traducción disponible.
Incluye los cambios manuales realizados localmente en los bytes de la traducción anterior que proporciones. El procesador del formato puede reutilizar el contenido sin cambios y traducir el contenido modificado. En JSON común, omitir el archivo de origen anterior impide reutilizar el contenido cuyo origen no cambió. Otros formatos pueden incorporar el contenido de destino existente según sus propias reglas de combinación. Conserva la versión base completa cuando necesites distinguir entre un cambio en el origen y un mensaje sin cambios.
Una solicitud con ámbito limitado mediante keyScope o termScope requiere una traducción anterior para cada idioma de destino. JSON, JSONC, TypeScript y PHP regeneran las cadenas seleccionadas, incluidos los valores de origen sin cambios, y las integran en el contenido de destino existente. YAML, YAML con raíz de idioma y YAML de OpenAPI pueden reutilizar el contenido seleccionado sin cambios cuando se proporciona un archivo de origen anterior. XCStrings puede reutilizar valores de destino integrados o proporcionados incluso sin un archivo de origen anterior. Por eso, seleccionar una unidad no siempre genera nuevo trabajo de traducción.
Proporciona al motor la terminología o la regla deseada antes de solicitar la regeneración y revisa el contenido de destino resultante. Si necesitas corregir la redacción con palabras exactas, edita directamente el contenido de destino para no depender de que la regeneración produzca una frase específica.
Antes de crear un trabajo posterior, almacena una versión base mediante PUT /v2/organizations/:orgId/localization/artifacts/:address, con autenticación y los bytes del archivo como cuerpo. Esta ruta requiere acceso de traducción a un motor de la organización y devuelve los metadatos del artefacto. Se aplican el mismo límite de 25 MiB y las mismas verificaciones de hash.
Descarga primero los resultados en archivos temporales. Antes de reemplazar los archivos de la aplicación, compáralos tanto con la revisión de origen enviada como con los cambios realizados en el contenido de destino desde el envío. Conservar las traducciones revisadas explica el flujo de trabajo correspondiente de la CLI.