Translation config options

Experience Workspace’s translation works out-of-the-box with Google Translate and requires no additional configuration. However translation offers rich configuration options to support your individual translation needs.

This document explains the configuration options available. For instructions on how to configure these options for translation, please see the document Set up translation. For example configurations to support various translation services, please see the document Translation config samples.

Config sheet structure

Localization is driven by a single translate config sheet stored at {{org}}/{{site}}/.da/translate. It is a multi-tab sheet where each named tab controls a different part of the localization, translation, and rollout pipeline.

config tab options

The config tab holds key / value rows to define your translation service, conflict resolution, and other general translation configuration options. Any key you do not set falls back to a sensible default.

Translation service options

These keys tell Experience Workspace which translation provider to use. An environment (such as prod or stage) groups a set of endpoint keys together so you can switch between them when you start a project. Each environment supplies its own translation.service.{env}.* keys.

Key
Description
Value
translation.service.name
The connector that handles sending and retrieving content. Defaults to Google.
Google, Smartling, or Trados

translation.service.all.env
Comma-separated list of environments to expose in the Options step. The first entry is the default.
stage, prod

Each provider requires a different set of per-environment keys.

Google

The built-in default. It requires no credentials, and the sample configs use a single prod environment.

Key
Description
Example
translation.service.{env}.origin
Base URL of the Google translation endpoint.
https://translate.da.live/google

translation.service.{env}.link
Reference URL shown to authors.
https://cloud.google.com/translate/docs/overview

Smartling

This service requires a Smartling account. The sample configs expose stage and prod environments.

Key
Description
Example
translation.service.{env}.origin
Base URL of the Smartling proxy endpoint.
https://translate.da.live/smartling

translation.service.{env}.link
Smartling dashboard URL authors can follow to view the job.
https://dashboard.smartling.com/app/accounts/{ACCOUNT_ID}/account-jobs/

translation.service.{env}.projectId
Smartling project identifier.
{PROJECT_ID}

translation.service.{env}.userId
Smartling user identifier.
{USER_ID}

translation.service.{env}.userSecret
Smartling user secret.
{USER_SECRET}

Trados

This service requires a Trados account. Trados authenticates via OAuth and uses apiEndpoint rather than origin. The sample configs use a single prod environment.

Key
Description
Example
translation.service.{env}.apiEndpoint
Trados Language Cloud API base URL.
https://lc-api.sdl.com/public-api/v1

translation.service.{env}.authEndpoint
OAuth 2.0 token endpoint.
https://sdl-prod.eu.auth0.com/oauth/token

translation.service.{env}.clientId
Trados OAuth client ID.
translation.service.{env}.clientSecret
Trados OAuth client secret.
translation.service.{env}.tenantId
Trados tenant identifier.
translation.service.{env}.audience
OAuth audience.
https://api.sdl.com

Credentials such as userSecret and clientSecret stay in the config sheet. Restrict who can read and edit .da/translate accordingly.

Conflict resolution

These keys decide what happens to existing destination content at each stage of the pipeline. The value is a comma-separated list of choices. The first choice is the default, and authors can change it per project in the Options step of the translation project. overwrite replaces the destination content, while merge runs a regional diff so region-only edits are preserved.

Key
Applies when
Value
sync.conflict.behavior
Sources are synced into the translation (source) folder.
overwrite, merge

translate.conflict.behavior
Translated content is returned from the service.
overwrite, merge

copy.conflict.behavior
A source is copied into a region.
overwrite, merge

rollout.conflict.behavior
Content is rolled out to a locale.
overwrite, merge

Source and completion

Key
Description
Value
source.language
Name (matching a row in the languages sheet) of the language treated as the source of truth. Sets the folder content is sent from. Defaults to the site root.
English

complete.aem.preview
Automatically preview documents after a project completes. Ignored if merge conflicts exist.
on / off

complete.aem.publish
Automatically publish documents after a project completes. Ignored if merge conflicts exist.
on / off

translation.service.supports.duedate
When set, shows a Due date field in Options. The chosen date is passed to the service as a due date (used by Trados).
yes

Custom service options

Custom options let a connector surface extra fields in the Options step of the translation project. The key takes the form translation.service.custom.{type}.{name}:

The value is a pipe-separated list of choices. Each choice may use label=value to show a friendly label while sending a different value. For example, a key of translation.service.custom.option.Priority with a value of Standard=std | Rush=rush renders a Priority dropdown whose selection is sent as std or rush.

languages tab options

The languages tab defines all languages (and their locales) available for translation and rollout.

Column
Description
Example
name
Display name of the language. Referenced by source.language.
German

code
Language or locale code.
de, en-GB

location
Folder where this language's content lives.
/langstore/de

actions
Comma-separated actions offered for the language. Skip is always added automatically.
Translate, Rollout

locales
Comma-separated locale paths this language rolls out to. Enables the Rollout action.
/de, /at, /ch_de

default locales
Optional subset of locales that is active by default.
/de, /at

source language
Optional. Name of another language this one derives from.
English

trados location, trados project template
Trados target folder and project template id.

custom-doc-rules tab options

Do not translate (DNT) rules mark content that should be sent to the service untranslated. The custom-doc-rules tab has two columns (block, rule) and defines block-level DNT for documents, written as a plain-language query.

Each rule pairs one or more blocks (in the block column, comma-separated) with a short plain-language query (in the rule column). A query combines an action (dnt, do-not-translate, or translate), an optional target (col, row, or cell with a number, a range like 1-2, or a negative index like -1), and an optional if or unless condition (is, contains, starts with, has element). Wrap values in double quotes (“). When you use translate ... if ..., anything that does not match the condition is left untranslated.

block
rule
Result
section-metadata

do-not-translate
DNT the entire block.
metadata

dnt col 1
DNT the first column (the keys) of every row while still translating the values.
metadata, card-metadata

dnt col 1
Apply the same rule to several blocks at once.
metadata

translate col 2 if col 1 is "title" or "description"
Translate the second column only when the first cell is title or description; leave every other row untranslated.
metadata

dnt if col 1 is "robots"
DNT the whole row whenever its first cell is robots.
columns

dnt col -1
DNT the last column of every row.
cards

dnt col 1-2
DNT the first two columns of every row.
marquee

dnt col 1 if col 1 starts with "#"
DNT hex or color values in the first column, but translate normal text.

dnt-content-rules tab options

Do not translate (DNT) rules mark content that should be sent to the service untranslated. The dnt-content-rules tab has one column (content) and contains literal strings that are never translated anywhere on the page.

Each row of the tab is a literal string that is left untranslated wherever it appears on the page.

content
Result
Adobe Photoshop
A product name is kept verbatim everywhere it appears.
do not translate me
An exact phrase preserved as-is.
#FFCC00
A hex color value preserved.
/products/
A URL path fragment preserved.

dnt-sheet-rules tab options

Do not translate (DNT) rules mark content that should be sent to the service untranslated. The dnt-sheet-rules tab has two columns (pattern, action) and contains value patterns for spreadsheet and JSON cells.

Each row matches cell values in the spreadsheet and JSON content. Conditions are equals, beginsWith, or exists, and multiple options are separated by double-pipe (||).

pattern
action
Result
beginsWith(http:// || https://)

dnt
Any cell whose value is a URL.
beginsWith(/)

dnt
Any cell that is a site-relative path.
equals(null)

dnt
Cells whose value is exactly null.
equals(true || false)

dnt
Boolean-like values.

dnt tab options

Do not translate (DNT) rules mark content that should be sent to the service untranslated. The dnt tab has two columns (dnt-sheet, dnt-columns) and is a whole-sheet or per-column DNT for JSON sheets.

This tab targets whole sheets or specific columns in JSON. Columns such as :translate, :uid, :rollout, and :regional are always excluded automatically, and a :translate value of no skips an entire row.

dnt-sheet
dnt-columns
Result
prices

*
DNT the entire prices sheet.
*

key, path
DNT the key and path columns in every sheet.
products

sku, url
DNT only the sku and url columns of the products sheet.