Localizar un catálogo de cadenas mediante la API

El formato indexado de Transept es .tstrings.json: una lista de unidades, cada una con un id estable, un origen (source) y, opcionalmente, un contexto (context: qué es la cadena y dónde aparece), una longitud máxima (max_length) y marcadores de posición (placeholders). El id actúa como contrato: permite que las traducciones mantengan su identidad tras las reimportaciones, que el estado de revisión se conserve y que la exportación indexe cada idioma. Ambos campos adicionales tienen una utilidad práctica: el contexto llega al modelo como guía de traducción y el límite de caracteres se aplica mediante un sistema automático de acortamiento y reintento.

Los archivos CSV, gettext PO y XLIFF se importan como las mismas unidades indexadas a través de la aplicación o del endpoint de carga; consulte archivos de cadenas para ver la correspondencia de cada formato. Este artículo trata sobre cómo gestionar el ciclo desde el código, donde .tstrings.json es el formato nativo.

Envíe una solicitud POST /documents/import-strings con el catálogo en formato JSON. Los idiomas de destino se determinan siguiendo un orden de prioridad: si se especifica target_language o target_languages en la solicitud, estos prevalecen; de lo contrario, se usan los target_locales del encabezado del catálogo. Si no se encuentra ninguno, la llamada fallará de inmediato con el error no_target_languages en lugar de importar un documento sin destinos. La llamada devuelve un processing_job_id; realice peticiones periódicas (poll) a GET /document-jobs/{id} hasta que la importación finalice y obtenga los ID de los documentos.

Las traducciones que el archivo ya incluya (targets: {de: "…"}) se cargan como la traducción activa de cada cadena, de forma gratuita y sin necesidad de ejecutar un proceso, y alimentan su memoria de traducción de inmediato; es el mismo comportamiento que al importar traducciones existentes a través de la aplicación.

# BASE="https://app.transept.ai/api/public/v1"; KEY from Settings → Developer
curl -s -X POST $BASE/documents/import-strings \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"document": {
        "format": "transept-strings", "version": 1, "source_locale": "en",
        "target_locales": ["de", "fr", "uk"],
        "metadata": {"name": "App UI"},
        "units": [
          {"id": "app.save", "source": "Save", "context": "Toolbar button"},
          {"id": "app.greeting", "source": "Welcome, {name}", "context": "Dashboard header"}
        ]}}'
# → { processing_job_id }; poll GET /document-jobs/{id}

Vuelva a enviar el catálogo actual completo a POST /documents/{id}/import-strings, no uno recortado. El servidor detecta las diferencias por el ID de unidad y responde con los resultados (added, changed, unchanged, removed) junto con los delta_block_ids: los bloques exactos que requieren trabajo en cada versión de idioma. Pase ese objeto tal cual en el campo block_ids de una ejecución grupal y solo se traducirán esos bloques; también puede incluir run en la reimportación para procesar los cambios en la misma llamada.

Las unidades que no han cambiado conservan sus traducciones y cualquier revisión que ya se haya realizado; esta es la versión para la API de Ejecutar solo lo que ha cambiado. Corregir una sola cadena en un catálogo de cientos cuesta solo una cadena.

# 1. Re-submit the whole current catalog; the server diffs it by unit id
curl -s -X POST $BASE/documents/<master>/import-strings \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d @app-ui.tstrings.json
# → { units: {added, changed, unchanged, removed}, delta_block_ids: {<doc_id>: [block ids]} }

# 2. Feed delta_block_ids VERBATIM into a group run; only those blocks translate
curl -s -X POST $BASE/group-runs \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"document_id": "<master>", "template_id": "end_to_end",
       "target_languages": "all", "block_ids": { "<doc_id>": ["<block id>", "…"] }}'

GET /documents/{id}/content?format=strings en el documento maestro devuelve un único archivo .tstrings.json con las traducciones de todos los idiomas indexadas por ID de unidad: una sola llamada, lista para confirmar cambios o reincorporarla a su proceso de compilación. El mismo endpoint ofrece versiones por idioma (markdown, html, csv, xliff, tmx) si su flujo de trabajo requiere un formato de transferencia específico; la tabla completa se encuentra en Automatizar Transept con la API.

En el caso de los catálogos importados como CSV, PO o XLIFF, la exportación del archivo original completa las celdas y entradas de su propio archivo (respetando byte a byte lo que subió, con las traducciones añadidas), de modo que el archivo pueda cargarse de nuevo directamente en el sistema del que proviene.

curl -s "$BASE/documents/<master>/content?format=strings" \
  -H "Authorization: Bearer $KEY"
# → one .tstrings.json with every language keyed by unit id