Working with Translation Workbench programmatically

If your company has offices in different locations I am sure you have heard about Translation Workbench. Translation Workbench is a tool that allows you to translate Salesforce texts to different languages. In this post I want to dig into how translations are implemented in the system, and how to work with them through the metadata API.

Translations are stored through different metadata types. You should be aware of these top-level ones:

• Translations: this metadata type holds translations for customApplications, customLabels, customPageWebLinks, customTabs, flowDefinitions, globalPicklists (before API 37), quickAction, reportTypes and scontrols.
• StandardValueSetTranslation (after API 37): contains details for a standard picklist translation.
• GlobalValueSetTranslation (after API 37): contains details for a global picklist translation.
• CustomObjectTranslation: contains details for the translation of a custom object, including its fields, fieldsets, recordtypes, picklists (before API 37) etc, as well as for custom settings and custom metadata types.

Bear in mind there are some gaps between the Metadata API and the Translation Workbench (eg: custom app description), but most of the translatable texts are supported by the Metadata API.

These top-level metadata types will be stored as folders in your source code. Here you have a sample repository in which translations have been provided for custom objects (CustomObjectTranslation metadata type) and custom labels (Translations metadata type):

Inside each folder we will have a set of files. In the case of custom objects, we will have a file per object and language. In the case of translations, we will have a file per language.

Custom Object Translations folder

The only way to work with Translation Workbench programmatically is by using the Metadata API. In these examples, I will use workbench for simplicity, but you can automate the usage of Metadata API with the ant migration tool, or even in Apex, using this great wrapper.

These are the operations that you can automate using the Metadata API:

<Package xmlns="http://soap.sforce.com/2006/04/metadata">
   <fullName>MyPkg</fullName>
   <types>
     <members>OrgPreference</members>
     <name>Settings</name>
   </types>
   <version>40.0</version>
</Package>

2) Retrieve in workbench by using above package.xml

3) Download the zip, unzip it

4) Go to unpackaged/settings/OrgPreference.settings, and change the value to ‘false’ or  ‘true’ for ‘Translation‘.

5) Zip unpackaged directory

6) Deploy the zip in workbench

This will have the same effect as enabling it from translation settings:

<Package xmlns="http://soap.sforce.com/2006/04/metadata">
   <types>
       <members>*</members>
       <name>Translations</name>
   </types>
   <version>27.0</version>
</Package>

<?xml version="1.0" encoding="UTF-8"?>
<Translations xmlns="http://soap.sforce.com/2006/04/metadata"/>

5) Zip and deploy it.

6) German is added as a supported language.

Bear in mind although German has been added, you will need to mark it as Active and add translators manually. I haven’t found a way to do this through metadata API.

Retrieve / Deploy translations for a given language to the Translation Workbench: follow the same process as the previous one, indicating the translations that you want to upload, using the correct metadata type (Translations, StandardValueSetTranslation, GlobalValueSetTranslation or CustomObjectTranslation) and file structure with the desired translations.