API
Translate JSON and files, follow their progress, and download completed translations from your server.
Use the Lingo.dev API to translate content your application owns. A localization job combines an engine, source language, target languages, and one or more documents. Each document tracks a target for each requested language. Most formats produce separate target files; Apple String Catalogs combine languages in one file.
The API base URL is https://api.lingo.dev/v2. Keep API credentials on your server. Start with your first translation request to translate two messages and save the result.
Choose your input #
| Your content | Start here |
|---|---|
| A JSON object already held by your application | Translate JSON. Send the object directly in the create request. |
| Files such as JSON, Markdown, HTML, or mobile resources | Translate documents. Upload the original bytes and download files in the same format. |
| Several documents or target languages | Create a translation job. One job can contain both inline JSON and uploaded files. |
All three follow the same lifecycle:
- Create a job and save its ID with your source revision.
- Upload every artifact listed in the response's
uploadsarray. Inline JSON sources are stored during creation. - Start the job.
- Read its progress until the required document targets have completed.
- Download each completed target from its
status.downloadUrl.
Creation saves the work to perform; starting it admits the work and begins processing. A successful create response is not a translated result.
Estimate the work before creating a job when you need to inspect reuse and approximate cost.
Configure the translation #
Select an engine explicitly with engineId. It supplies models, glossaries, rules, and brand voice, together with the translation pipeline. The API key must have translation access to that engine.
For JSON, add document-specific context, hints, and protected paths through format.options. For a later revision, provide the previous source and translations to reuse unchanged content.
Human review lets authorized reviewers approve or edit eligible translations before the pipeline continues. The review workflow guide explains how to connect submission, review, and delivery.
Keep application state with the job #
Persist the job ID, source revision, document keys, and requested locales before moving on. Use the Idempotency-Key header when creating a job so an uncertain response can be retried without creating another job. Retrieve existing work before submitting a replacement.
Download completed targets even when another target fails. Publish a result only if it still belongs to the source revision your application expects. Build a translation workflow covers this coordination.
See authentication, errors, and the error catalogue for access and recovery.
Prepare and improve an engine #
Provisioning fills glossaries, rules, and brand voice from website content or text. Engine suggestions turn feedback into proposals that you can inspect and apply. Review generated guidance before relying on it for translation.