Short answer: translate only the human-readable text units inside a supported property value, then patch those translations back into a cloned structure. Preserve block keys, layout, settings, links, media and identifiers, and validate the result before it is saved to the target language variant.
Why is complex Umbraco content different?
A text box usually persists one string. A modern Umbraco page may persist nested content and layout data containing multiple blocks, element properties, keys, settings and references. Sending the entire JSON value to a model gives it an opportunity to rewrite structure that should never be translated.
A safe translation tool needs to understand the editor's persisted value, not merely recognise that the value happens to contain strings.
What parts should be translated?
| Usually translate | Usually preserve |
|---|---|
| Headings, summaries, body copy and captions | Block and element keys |
| Visible rich-text text nodes | HTML elements, link targets and attributes |
| Text list values and notes | Media and content selections |
| Accessible labels intended for visitors | Aliases, UDIs, URLs, colours, booleans and layout settings |
A safe extract, translate, patch and validate pipeline
- Extract: parse the supported persisted value and assign stable IDs to each translatable unit.
- Translate: send only those units, with the source and target culture and approved instructions.
- Patch: clone the original value and replace only units whose stable IDs match.
- Validate: reject the result if protected structure, keys or unit identity changed unexpectedly.
- Save a draft: write the validated value to the intended language variant for review.
How should Block List and Block Grid be handled?
Both editors combine content data with protected structure. Translation should walk supported element properties recursively while retaining content keys, settings keys, layout coordinates and block order. Nested blocks need the same rule at every level.
Block Grid layout metadata is not prose. Treating the complete JSON document as a translation prompt can move, remove or corrupt blocks even when the visible output initially looks plausible.
What about rich text?
Rich text requires HTML-aware extraction. Translate visible text while retaining elements, attributes, links and embedded references. Plain string replacement is unsafe because a model may alter URLs, remove markup or translate an attribute that code depends on.
How can custom property editors be supported?
A custom editor that persists plain text or compatible rich text can be mapped explicitly. A structured value needs an adapter that understands its real schema and can extract, patch and validate stable text units. Guessing from the presence of JSON or string values should fail closed.
Structured content places more demand on the model than plain prose, because markers and formatting must survive intact. If you are weighing model tiers for a block-heavy site, see choosing an AI provider and model and estimating AI translation costs.
Common questions
Can AI translate every property editor?
No. An editor should be translated only when its storage contract is understood. Pickers, configuration, dates, numbers and arbitrary JSON normally have no safe translation meaning.
Will translating a block create a new block?
It should not. The target variant should preserve the corresponding block identity and structure while changing only approved text values.
Can existing custom editors opt in?
Yes. Omni supports explicit simple mappings and code adapters, while keeping unknown persisted shapes unsupported.
Check your editor compatibility
See the complex-content feature overview, review supported property editors, and use the custom editor extension guide when a site-specific value needs an adapter.