How to translate Block List, Block Grid and complex Umbraco content

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?

A safe extract, translate, patch and validate pipeline

1. Extract: parse the supported persisted value and assign stable IDs to each translatable unit.
2. Translate: send only those units, with the source and target culture and approved instructions.
3. Patch: clone the original value and replace only units whose stable IDs match.
4. Validate: reject the result if protected structure, keys or unit identity changed unexpectedly.
5. Save a draft: write the validated value to the intended language variant for review.

Umbraco backoffice

Enlarge ↗

×

A preview should show the text that can be translated and report unsupported values before a job starts.

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.

Support for community and third-party editors

Omni's editor support goes beyond Umbraco's built-in text and block editors. It includes selected editors from popular community packages, so translation can cover more of the content your site already uses:

• Contentment: TextInput, TextboxList, ContentBlocks and Notes.
• SeoVisualizer and MetaMomentum: supported SEO titles, descriptions and social text.
• UmbNav: navigation names and descriptions, with links and hierarchy preserved.
• Community Heading: heading text, including headings nested in supported block editors, with the heading level preserved.
• Dyfort/our HTag Editor: text with heading and alignment choices preserved; Ph Heading uses HTML-aware handling to preserve inline formatting.
• UmbHost.Tables: prose cells in supported tables configured with rich text disabled.

These integrations recognise known stored formats without requiring Omni to install the community packages. See the supported property editors and compatibility details for editor aliases, supported versions and the values each integration translates.

Using SeoVisualizer or MetaMomentum? Follow the SEO title and meta description translation guide for a focused workflow with these editors.

Extend support through configuration or code

Omni is extensible, so a site-specific property editor does not have to mean copying content out of Umbraco to translate it. There are two ways to bring additional editors into the same translation workflow:

• Configuration mappings: when an editor stores plain text or compatible HTML, map its alias to PlainText or RichText through ContentTranslation.PropertyEditorMappings. This reuses Omni's existing parsers without writing a custom adapter. See how to map simple editors in configuration.
• Code adapters: for a structured value, implement IContentTranslationPropertyEditorAdapter to extract text, patch translated units and validate the result, then register it through an Umbraco composer. See the adapter contract and registration example.

Both approaches work with the editor's actual stored value. Configuration handles compatible text formats; an adapter adds knowledge of a more complex schema while preserving its non-text fields. This lets developers extend translation support to match the site's content model.

Umbraco backoffice

Enlarge ↗

×

The target variant retains the normal Umbraco editing experience after supported values are reconstructed.

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. Use configuration mappings for plain text or compatible rich text, or a code adapter for structured values. Check the supported editors list first: your community editor may already be covered.