Traducir documentos

Sube archivos de origen y traducciones anteriores, inicia un trabajo de localización y descarga los archivos resultantes.

Usa los trabajos de traducción de documentos para traducir archivos sin alterar 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 #

Define format.type en cada documento:

FormatoTipo
JSON / JSONCjson / jsonc
Markdown / MDX / Markdocmd / mdx / markdoc
HTMLhtml
TypeScript / PHPtypescript / php
YAML / YAML con raíz de idioma / YAML de OpenAPIyaml / yaml-root-key / yaml-openapi
Android / ARB de Flutterandroid / flutter
Cadenas de Apple / diccionarios de plurales / catálogos de cadenasxcode-strings / xcode-stringsdict / xcode-xcstrings
Gettext / XLIFF / SubRippo / xliff / srt
Texto sin formatotxt
Tabla CSV con una columna por idiomacsv
Propiedades de Javaproperties
Contenido de Payloadpayload

Las referencias de formatos explican las estructuras de los archivos y los controles. format.options de la API utiliza el contrato de documento; la configuración de la CLI adapta los nombres de sus propias opciones a este contrato. Por ejemplo, la API utiliza frontmatterFields para Markdown y componentProps para las propiedades de los componentes. Los selectores de claves JSON utilizan JSONPath.

Configura las opciones de formato #

Puedes omitir format.options para usar los valores predeterminados. Configura solo las opciones compatibles con el tipo seleccionado:

TipoOpciones
json, jsoncOpciones de JSON: reglas de claves, ámbitos, contexto, indicaciones e inyección del idioma.
typescript, php, yaml, yaml-root-keylockedKeys, preservedKeys, ignoredKeys (valor predeterminado: []); keyScope y termScope opcionales, pero no pueden estar vacíos.
mdfrontmatterFields (valor predeterminado: ["$.title", "$.description"]); termScope opcional, pero no puede estar vacío.
mdx, markdocOpciones de Markdown más componentProps (valor predeterminado: []).
htmlcomponentProps (valor predeterminado: []), además de los atributos traducibles integrados en el procesador.
xcode-stringsdictlockedKeys y preservedKeys (valor predeterminado: []); termScope opcional, pero no puede estar vacío.
flutter, xcode-strings, xcode-xcstrings, android, yaml-openapitermScope opcional, pero no puede estar vacío.
csvkeyColumn opcional: el encabezado de la columna de claves (valor predeterminado: la primera celda del encabezado).
propertieslockedKeys, preservedKeys, ignoredKeys (valor predeterminado: []) y keyScope opcional, que no puede estar vacío, se cotejan con la clave completa como patrones de estilo antiguo o como JSONPath si un patrón empieza por $; termScope opcional, que no puede estar vacío; lockedPatterns (valor predeterminado: []), expresiones regulares RE2 que se mantienen sin traducir en los valores.
payload, po, xliff, srt, txtSin opciones adicionales.

Las reglas de claves, los ámbitos de claves y los campos de metadatos iniciales utilizan 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, al proporcionar ambos se selecciona su intersección. Ambos ámbitos requieren traducciones existentes en las que integrar el resultado. La selección y la reutilización dependen del formato, como se describe en actualizaciones incrementales. Estas opciones de la API difieren de la compatibilidad de la CLI con los formatos de --key.

Una regla de propiedades de componentes contiene props, una matriz no vacía de nombres de propiedades, y, opcionalmente, components, una matriz no vacía que limita la regla a los componentes especificados por su nombre. Si omites components, la regla se aplica a cualquier componente. Para MDX:

json
{
  "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 conocer cómo se protegen el código y las expresiones y cómo funciona la reconstrucción.

Crea el trabajo con direcciones de artefactos #

Calcula el hash de los bytes exactos que vayas a subir. En Node.js:

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 con la dirección resultante como source del documento:

json
{
  "engineId": "YOUR_ENGINE_ID",
  "sourceLocale": "en",
  "targetLocales": ["de"],
  "documents": [
    {
      "key": "messages/en.json",
      "format": { "type": "json" },
      "source": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
  ]
}

Sustituye la dirección de ejemplo por el hash calculado. Guarda el ID del trabajo devuelto. uploads enumera los artefactos de entrada que faltan en el almacenamiento; no hace falta volver a subir el contenido ya almacenado.

Sube 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. Sube 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 máximo, se devuelve RequestBodyTooLarge. Si calculas el hash del texto y luego cambias sus finales de línea antes de subirlo, los bytes cambian y la verificación falla.

Llama a POST /v2/localization/jobs/:id/start cuando todas las subidas se hayan completado correctamente. Solo se aceptan subidas de artefactos antes de que se inicie el trabajo. Consulta el progreso del trabajo por idioma de destino y 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 nuevo artefacto de origen.
  • previousSource: la dirección de origen utilizada para la revisión anterior.
  • previousTranslations: una entrada { "locale": "de", "artifact": "..." } por cada traducción disponible.

Incluye las modificaciones manuales locales 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 estándar, omitir el archivo de origen anterior impide reutilizar el contenido cuyo origen no ha cambiado. Otros formatos pueden incorporar contenido de destino existente según sus propias reglas de combinación. Conserva la versión de referencia completa cuando necesites distinguir entre una modificación del origen y un mensaje sin cambios.

Una solicitud limitada a un ámbito 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 archivo de destino existente. YAML, YAML con raíz de idioma y YAML de OpenAPI pueden reutilizar el contenido seleccionado que no haya cambiado si se proporciona un archivo de origen anterior. XCStrings puede reutilizar valores de destino integrados o proporcionados incluso sin un archivo de origen anterior. Por tanto, seleccionar una unidad no siempre implica un nuevo trabajo de traducción.

Proporciona al motor la terminología o la regla deseada antes de solicitar la regeneración y revisa el resultado en el idioma de destino. Si necesitas una corrección con una redacción exacta, edita directamente la traducción para no depender de que la regeneración produzca una frase concreta.

Antes de crear un trabajo posterior, almacena una versión de referencia 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 comprobaciones del hash.

Descarga primero los resultados en archivos temporales. Antes de sustituir los archivos de la aplicación, compáralos tanto con la revisión de origen enviada como con cualquier modificación de las traducciones realizada desde el envío. Conservar las traducciones revisadas explica el flujo de trabajo correspondiente de la CLI.