Translating content

Once a provider is configured and a license (or trial allowance) is active, you can translate content from two places in the backoffice: the document workspace and individual Block Grid / Block List properties. Both routes call the same Management API and respect the same provider and licensing rules.

Translate a whole variant from the workspace

1. Open a content node that varies by culture.
2. Switch to the target-language variant tab (the one you want to populate).
3. Click Translate from… in the workspace action bar.
4. Pick the source culture in the picker modal.
5. Confirm. The plugin copies every culture-varying property from the source variant, translates the value, and saves the result on the current variant.

Properties whose editor alias is in SkipPropertyEditorAliases are skipped. Properties that don't vary by culture are also skipped — they have no per-culture value to translate.

Translate a single block

On any Block Grid or Block List property, open the property's action menu (the … icon) and pick Translate block. The same source-culture picker appears, and only that one property is rewritten. Useful when you've edited part of a page in the source language and don't want to overwrite manual edits elsewhere on the variant.

Block Grid and Block List support

The block walker descends into the property's JSON payload and translates string values inside contentData. By default, settingsData is left untouched — settings often hold colour codes and layout flags that you don't want translated. To translate settings too, set TranslateSettingsData to true in appsettings.json.

Property values that are structured JSON objects (not strings) are passed through unchanged — UmbracoTranslator does not introspect unknown shapes. Nested block editors are not recursively walked yet; a Block Grid inside a Block Grid only gets its outer-level string values translated.

Management API

The same flows are available over the Management API for scripted bulk operations. Requests are gated by the BackOfficeAccess policy and the active-license filter — sign in to the backoffice (or use a backoffice access token) before calling.

Translate a whole node

POST /umbraco/management/api/v1/translator/content/{key}/translate
Content-Type: application/json

{
  "sourceCulture": "en-US",
  "targetCulture": "nl-NL",
  "overwrite": false
}

Translate a single property

POST /umbraco/management/api/v1/translator/content/{key}/property/{propertyAlias}/translate
Content-Type: application/json

{
  "sourceCulture": "en-US",
  "targetCulture": "nl-NL"
}

Both endpoints return a result object describing which properties were touched, which were skipped (and why), and how many source words were billed against the license. providerAlias is optional on the request body — omit it to use the configured DefaultProviderAlias.

Configuration reference

All options live under Umbraco:UmbracoTranslator in appsettings.json.

• DefaultProviderAlias — provider used when the request doesn't specify one. Defaults to echo; set to google-cloud-translation for production.
• TranslateBlockGridContents — when true (default), Block Grid / Block List contentData string values are translated.
• TranslateSettingsData — when true, block settingsData string values are also translated. Default false.
• SkipPropertyEditorAliases — array of property-editor aliases to skip entirely. Useful for tag pickers, media pickers, and other properties whose value is an identifier, not text.
• GoogleCloud:ApiKey — Google Cloud Translation API key. Required only when DefaultProviderAlias is google-cloud-translation.