Translating page text with Translations components

A Workday Extend app shows page text in each user's Preferred Display Language once the PMDs use translation keys instead of hard-coded strings and each language supplies a value for every key. The values live in one Translations component per locale, and each locale must also be listed in the Site Metadata (SMD) languages array (Add Translations).

Three pieces have to agree: the SMD list of languages, one file per language with the same set of keys, and the PMD bindings that use those keys.

Add each language to the SMD languages array

A new app's languages array contains en-US, and the array can't be empty. Add an entry for every language you will ship:

"languages": [
  { "code": "en-US", "description": "English (United States)" },
  { "code": "fr-FR", "description": "French (France)" },
  { "code": "de-DE", "description": "German (Germany)" }
]

code is required; description is optional (Reference: Site Metadata). The same array does a second job: date and numeric widgets format values for a user's locale only when that locale's code is in languages. An app with no translations still benefits from listing the locales its users work in; the formatting side is covered in PMD date, number and currency formats.

Create one Translations file per locale (key=value)

In App Builder, open Page Configurations > Translations and add a Translations component for each language, named with its locale code: en-US, fr-FR, de-DE. On disk these are .properties files in presentation/presentationLabels, named <language>-<COUNTRY>.properties, with ISO 639-1 language and ISO 3166-1 country codes (Translate Widgets Using the Workday Extend Plugin for IntelliJ).

Each line is key=value:

# en-US
equipmentRequestTitle=Request Equipment
requestedItem=Requested Item
submitHelp=Complete the fields below and submit your request.

# fr-FR
equipmentRequestTitle=Demander un équipement
requestedItem=Article demandé
submitHelp=Remplissez les champs ci-dessous et soumettez votre demande.

The rules Workday sets for these files:

  • There must be a default language file (such as en-US) plus one per supported language, and all of them must use the same keys.
  • Use UTF-8. Workday's Add Translations page also allows a Unicode escape in place of a non-Latin character, for example home=\u5BB6.
  • A value that runs over several lines ends each line with \; it still displays as one line. A value may contain =.
  • Each file is limited to 100 KB.

Keep keys stable: renaming one means changing every language file and every PMD that binds it.

Bind PMD label, title and value to presentationLabels

Replace each hard-coded label, title or value with a binding to presentationLabels:

{
  "type": "text",
  "id": "requestedItem",
  "label": "<% presentationLabels.requestedItem %>"
}

Workday's Vehicle Registration with Translations sample does this throughout, for example "title": "<% presentationLabels.VehicleDetails %>" on a section and "value": "<% presentationLabels.PleaseCompleteTheFieldsBelow %>" on help text.

In IntelliJ with the Workday Extend plugin, right-click a hard-coded label, title or value and choose Create translation key. The plugin writes the key to the language file and swaps the string for the binding. It only works on hard-coded values; it cannot convert a value that is already a binding, so a binding that already exists has to be changed by hand.

What this does not translate

The label files cover the text your pages display. Other text stays as it is:

  • Data. Values stored in your business objects are not translated. Workday lists Extend business objects as not translatable, where delivered objects are (Reference: Workday-Delivered vs. Workday Extend Business Objects). A status of "Approved" saved as text displays as "Approved" to every user. Store codes and translate their display labels on the page, or keep a label per language in your own lookup object.
  • The app title. The SMD titles array accepts a languageCode, but Workday currently supports only en-US there.

If the requirement really is translating user-entered content, Workday's AWS integration exposes Amazon Translate operations such as TranslateText to Extend apps (Reference: Allowed Amazon Translate APIs). That is machine translation of data, a separate design from label files.

Testing translations: App Preview will not show them

App Preview displays only en-US labels for every signed-in user (Extend App Preview), so a French label that looks missing in preview may be fine. Test in the tenant instead, as part of your normal Extend testing:

  1. Upload the app to App Hub and deploy it. All files in presentationLabels become part of the app artifact.
  2. Sign in as a test user, change their Preferred Display Language to the target language, and open each page.
  3. Compare each page against the language file, including messages and validation text.
  4. Switch back to English and confirm nothing changed there.

When a label is blank or wrong in one language only, check two things first: that the key exists in that language's file, and that the key in the PMD binding is spelled exactly as in the files. Workday requires every file to carry the same keys, so diffing the key lists of the files before each upload catches both.

Sources checked