Translate documents

Upload source files and previous translations, start a localization job, and download the resulting files.

Use document jobs to translate files while preserving their format. A job can contain several files and target languages. The API addresses each file by the SHA-256 hash of its exact bytes.

You need an API key, organization ID, and engine ID. The file-localization guide provides a complete Node.js example.

Choose a format #

Set format.type on each document:

FormatType
JSON / JSONCjson / jsonc
Markdown / MDX / Markdocmd / mdx / markdoc
HTMLhtml
TypeScript / PHPtypescript / php
YAML / locale-root YAML / OpenAPI YAMLyaml / yaml-root-key / yaml-openapi
Android / Flutter ARBandroid / flutter
Apple strings / plural dictionaries / string catalogsxcode-strings / xcode-stringsdict / xcode-xcstrings
Gettext / XLIFF / SubRippo / xliff / srt
Plain texttxt
CSV table with a column per localecsv
Java propertiesproperties
Payload contentpayload

The format references explain the file structures and controls. API format.options uses the document contract; CLI configuration translates its own option names into this contract. For example, the API uses frontmatterFields for Markdown and componentProps for component properties. JSON key selectors use JSONPath.

Set format options #

format.options can be omitted to use defaults. Set only options supported by the selected type:

TypeOptions
json, jsoncJSON options: key rules, scopes, context, hints, and locale injection.
typescript, php, yaml, yaml-root-keylockedKeys, preservedKeys, ignoredKeys (default []); optional nonempty keyScope and termScope.
mdfrontmatterFields (default ["$.title", "$.description"]); optional nonempty termScope.
mdx, markdocMarkdown options plus componentProps (default []).
htmlcomponentProps (default []), in addition to the handler's built-in translatable attributes.
xcode-stringsdictlockedKeys and preservedKeys (default []); optional nonempty termScope.
flutter, xcode-strings, xcode-xcstrings, android, yaml-openapiOptional nonempty termScope.
csvOptional keyColumn, the header of the key column (default: the first header cell).
propertieslockedKeys, preservedKeys, ignoredKeys (default []) and optional nonempty keyScope, matched against the whole key as old-style patterns, or as JSONPath when a pattern starts with $; optional nonempty termScope; lockedPatterns (default []), RE2 regular expressions kept untranslated in values.
payload, po, xliff, srt, txtNo additional options.

Key rules, key scopes, and front matter fields use JSONPath queries. termScope selects whole source units containing any supplied term as a case-sensitive substring; "cat" can match "catalog". When a format supports both keyScope and termScope, supplying both selects their intersection. Both scopes require existing translations to merge into. Selection and reuse depend on the format, as described under incremental updates. These API options differ from the CLI's --key format support.

A component-property rule contains props, a nonempty array of property names, and optional components, a nonempty array restricting it to named components. Omitting components applies the rule to any component. For MDX:

json
{
  "type": "mdx",
  "options": {
    "frontmatterFields": ["$.title", "$.description", "$.sidebar.label"],
    "componentProps": [{ "components": ["Callout"], "props": ["title"] }]
  }
}

This translates the selected front matter and literal Callout titles alongside the document's prose. Check the format reference for protected code, expressions, and reconstruction behavior.

Create the job with artifact addresses #

Hash the exact bytes you intend to upload. In 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");

Create a job with the resulting address as the document's source:

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

Replace the sample address with the computed hash. Save the returned job ID. uploads lists input artifacts missing from storage; already stored content does not need uploading again.

Upload the bytes and start #

For each uploads entry, send an authenticated PUT to its uploadUrl with Content-Type: application/octet-stream and the original bytes as the body. Upload sources and any referenced previous files before starting.

Artifacts are limited to 25 MiB each. A hash mismatch returns ArtifactChecksumMismatch; an oversized file returns RequestBodyTooLarge. Hashing text and then changing its line endings before upload changes the bytes and fails verification.

Call POST /v2/localization/jobs/:id/start after all uploads succeed. Artifact uploads are accepted only before the job starts. Read the job's target progress, then download completed files from their returned URLs.

Update an existing document #

Keep three inputs for an incremental update: the new source, the previous source, and the current translation for each target locale. Supply:

  • source: the new source artifact address.
  • previousSource: the source address used for the previous revision.
  • previousTranslations: one { "locale": "de", "artifact": "..." } entry per available translation.

Include local human edits in the previous target bytes you supply. The format handler can reuse unchanged content and translate changed content. For ordinary JSON, omitting the previous source removes unchanged-source reuse. Other formats can adopt existing target content under their own merge rules. Keep the full baseline when you need to distinguish a source edit from an unchanged message.

A scoped request through keyScope or termScope requires a previous translation for every target locale. JSON, JSONC, TypeScript, and PHP regenerate selected strings, including unchanged source values, and merge them into the existing target. YAML, locale-root YAML, and OpenAPI YAML can reuse unchanged selected content when a previous source is supplied. XCStrings can reuse embedded or supplied target values even without a previous source. A selected unit therefore does not always become new translation work.

Give the engine the intended terminology or rule before requesting regeneration, and inspect the resulting target. For an exact wording correction, editing the target directly avoids depending on regeneration to produce a particular phrase.

Store a baseline before creating a later job with PUT /v2/organizations/:orgId/localization/artifacts/:address, authenticated with the file bytes as the body. This route requires translation access to an engine in the organization and returns artifact metadata. The same 25 MiB and hash checks apply.

Download results into temporary files first. Compare them with both the submitted source revision and any target edits made since submission before replacing application files. Preserve reviewed translations explains the corresponding CLI workflow.