Async Site Translator: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. It provides a useful starting point as you plan your implementation.

Translate a site's untranslated content

A site owner has added a secondary language to their site and wants everything that hasn't been translated yet rendered in it, without paying to re-translate content they've already handled.

To translate a site's untranslated content:

1. Optionally, call Check Sufficient Credits with the number of words you expect to translate, so you can warn the site owner before starting a job that would fail.
2. Call Translate Site with the site's primary locale as mainLocale, the locale to translate into as translatedLocale, and filterByStatus set to UNTRANSLATED_ONLY.
3. Store the jobId from the response.
4. Poll Get Translation Job Status with that jobId until jobState is COMPLETED or FAILED.
5. Read failedFields and show each failureReason to the site owner, so they can fix the content and run another job for it.

Refresh translations after content changes

When a site owner edits content that was already translated, those translations become outdated. Rather than re-translating the whole site, you can pick up only what changed.

To refresh outdated translations:

1. Call Translate Site with filterByStatus set to OUTDATED_ONLY, so the job covers only fields whose source content changed after they were translated.
2. Store the jobId from the response.
3. Poll Get Translation Job Status until jobState is COMPLETED or FAILED.
4. To cover content that was never translated in the same job, use UNTRANSLATED_AND_OUTDATED instead of OUTDATED_ONLY in step 1.

Translate one section of a site

A site owner wants to translate a single collection, such as their product catalog, rather than everything on the site. Narrow the job with the filter field.

To translate one section of a site:

1. Call List Site Schemas to find the schema whose content you want to translate, and take its id.

2. Call Translate Site with that schema in the filter:

   Copy

3. Store the jobId from the response.

4. Poll Get Translation Job Status until jobState is COMPLETED or FAILED.

To narrow the job further to specific items rather than a whole schema, filter on entity IDs instead, using {"entityId": {"$in": ["<ID_1>", "<ID_2>"]}}. Don't include a locale key in the filter: the job already scopes itself to mainLocale, and your own locale value overrides that scoping.