What the Contentstack connector does, which content it translates, and what you need before you start. For content and localisation teams running translation from Contentstack.
What it does
The connector sends content from your Contentstack stacks to TranslationOS for human or machine translation, and writes the translations back into the matching locale entries.
It is event based. Nothing is polled on a schedule, so a request starts the moment you ask for one.
Two ways to request a translation
You can use either method, or both at the same time on the same stack.
|
|
From a workflow stage |
From the Translated app |
|---|---|---|
|
How you start a request |
Move an entry to a translation workflow stage |
Submit from the Translated app in the entry sidebar |
|
Choose individual fields |
No. The whole entry is sent, following the field rules |
Yes. You pick the fields |
|
Includes referenced entries |
Yes, if reference depth is enabled on your account |
No. Only the entry you submitted |
|
How you set options |
Text patterns in the stage comment |
Form fields in the app |
|
Management token needed |
Yes |
No. The app uses OAuth |
|
Webhook needed |
Yes |
No |
|
Where you see status |
The workflow stage, plus a tracking comment |
Per language in the app: In Progress, Ready, or Unsupported |
If translation is already a step in your editorial process, use workflow stages. If you want editors to decide what gets translated entry by entry, use the app.
How content is handled
Each translatable field in an entry is sent as its own translation request. Each field is treated as the content type it actually is, whether that is plain text, Markdown, or HTML. Progress is tracked field by field, and partial updates do not force a full retranslation.
What gets translated
|
Field type |
Translated |
Notes |
|---|---|---|
|
Single line textbox |
Yes |
|
|
Multi line textbox |
Yes |
|
|
Rich text |
Yes |
|
|
JSON Rich text |
Yes |
|
|
Markdown |
Yes |
|
|
URL |
Partly |
Only the URL title. The URL itself is never sent, to avoid broken links |
|
Modular blocks, Global fields, Groups |
Yes |
When they contain supported fields |
|
Reference |
Optional |
Only if reference depth is enabled on your account |
|
Number, Boolean, Date, File, Select, Taxonomy, Custom |
No |
No translatable text, or no known structure |
If you keep translatable strings in a Custom field, they will not be picked up.
Rules that apply on top of field type
-
Fields marked Non-localizable in your content model are never sent.
-
Field visibility rules are not applied. A field hidden in the editor is still sent if it is localizable.
-
Reference fields are followed only when reference depth is set above zero on your account. The connector then scans until no further references are found and sends each referenced entry once.
-
Maximum character counts set in your content model are respected. Minimum counts are not. Not every Contentstack field type allows a character limit.
Limits
|
|
Limit |
|---|---|
|
Labels per request |
50, up to 50 characters each. Human translation only |
|
Tags per request |
10 key and value pairs, up to 50 characters each. Human translation only |
|
Machine translation context |
10 sentences |
|
Workflow stage name length |
32 characters, set by Contentstack |
|
App session token |
1 hour |
Before you start
You need a Contentstack admin account for most of the setup. Have these ready:
-
Your Contentstack API base URL
-
The full list of source and target languages, for every stack
-
A translation workflow with three consecutive stages
-
Your stack API key, for every stack
-
A management token, if you will work through workflow stages without the app
-
The environments translations should be published to, if you want automatic publishing