AgileApps Support Wiki Pre Release

Translation Workbench

From AgileApps Support Wiki

GearIcon.png > Administration > Account Management > Translation Workbench

The Translation Workbench makes it possible to deliver an application in one or more of the languages supported by the platform, by mapping words and phrases defined in custom platform elements to a different language.

About the Translation Workbench

By default, the platform runtime user interface (UI) is labeled in English. In order to make the platform more usable for a global audience, these Eligible Platform Elements can be customized with language labels. These configurable platform elements are presented in a language that is more familiar to users, which improves their effectiveness. Any of the Supported Languages can be selected. The Audit Log will reflect language translation, if it has been implemented.

Lock-tiny.gif

Lock-tiny.gif

Users that have the Manage Translation Workbench permission can View, Import or Export the translation tables. 

Although generally intended for localization of Custom Objects, the translation workbench can also be used to modify the labels associated with System Objects.

Developers can specify Java-style i18n labels and default values for Custom Labels.

Multiple languages can be enabled for a single platform tenancy. Individual users can select a default from the list of available languages.

Learn more: Language Translation

Load the Translation Workbench

In order to enable Multiple Language Translation, language labels must first be loaded to the Translation Workbench. Two methods are available to load the Translation Workbench:

Manual Edit
Use this option to change language labels individually
Import and Export
Use this option for mass changes to language labels

Manual Edit

To edit individual language translations:

  1. Click GearIcon.png > Administration > Account Management > Translation Workbench
  2. Use the following options to navigate to the element of interest:
    Language
    Choose one of the available languages from the list.
    (The choices are determined by the Company Information settings.)
    Elements
    Choose one of the Eligible Platform Elements for editing
    Type and Subtype:Optional, and are not presented with every Language + Element combination
  3. Click the [Edit] button
  4. Manually edit the Translated Display Label
  5. Click [Save]

Import and Export

To create a new language translation file in CSV format, follow this procedure:

Step 1: Export an existing language set.
Step 2: Change the language-designation for each entry in the file.
Step 3: Add the translated entries into the file using an external translation system.
Step 4: Re-Import the resulting file to create a new language option.
Considerations
  • Translation Id is unique to each tenancy
  • The import will fail if:
  • The order of the fields in the CSV file is changed
  • The Translation Id field is changed
  • Objects have two records in the translation export file, where Item Type is Object Singular Label and Object Plural Label

Export Translation Entries

To export an existing language to a file:

  • Click GearIcon.png > Administration > Account Management > Translation Workbench
  • Click the [Export Translation Entries] button
  • In the Translation Information section, select:
  • Language: Choose the language to export
  • Export Application wise Translation Labels: New properties are added in the translation export page. This option allows you to export application wise translation labels. Checkbox is unchecked by default.


Ljp 16240 img1.PNG


  • When you select the checkbox, you are shown a multi select application drop-down. You can choose the application that needs to be translated.


Ljp 16240 img2.png


  • In the Email Address Section, select:
    Email address
    Enter an email address
    A link to the CSV file is sent to this email address.

The contents of the CSV file can be translated to any desired language. It contains the labels for all Eligible Platform Elements.

Notepad.png

Note:

  • Application wise export of translation entries is not available in Admin Tenant.
  • Dependent objects are included in application wise translation entries export option.
  • You can import or export one language at a time using the translation workbench import/export feature.

Change Language Designation

A typical language translation files can contain thousands of records. Here is part of one exported from the platform:

Translation Id,Language,Item Type,Additional Info,Base Label,Translated Label
11eb24840b494736933dfea6ed13b50a,en,Object Singular Label,,Account,,
11eb24840b494736933dfea6ed13b50a,en,Object Plural Label,,Accounts,,

60ed42521fd54de5a24d294ee8494db9,en,Object Plural Label,,Active Employees,,
5f13c0b09d93427eb073a38c31146f68,en,Object Plural Label,,Benefits,,
443eeb61c2cf4e6da297bf80b09a5c2a,en,Object Plural Label,,Cases,,
58f403513d8d40bb9f0190cb0974add5,en,Object Singular Label,,Company,,
11ee93bca9f649ceadbee7a66ec163d4,en,Object Singular Label,,Compensation,,
c3d33c48ba104eefa2d56ae45f39c667,en,Object Plural Label,,Contacts,,

fa2d4a8bc6e24d4f8a3c6d2bcfcb6c1c,en,Section,Object:Contacts,Layout Name:Default Layout,Contact Information,,
da7d3db7e078419ebc583a1a4f061ea0,en,Section,Object:Contacts,Layout Name:Default Layout,Description Section,,
 . 
 .
 .

Note that the language-designation for each entry is "en" (English). When translating the language into Spanish, for example, you would do a search/replace to change each instance of ",en," to ",es,". (Adding the commas ensures that you don't make an unintended change.)

Import Translation Entries

To import the translation entries file:

  1. Click GearIcon.png > Administration > Account Management > Translation Workbench
  2. Click the [Import Translation Entries] button, and complete the following information:
    Language
    Specify the language to import
    Select the file to load
    Click the [Browse] button to navigate to the file
  3. Click [Save]


How to use the application wise translation effectively

  1. Export an existing language set from the development tenant.
  2. Change the language-designation for each entry in the file.
  3. Add the translated entries into the file using an external translation system.
  4. Re-Import the resulting file to create a new language option in the development tenant.
  5. While Packaging include Translation Work Bench for language.
  6. Install Package in TEST or PRODUCTION Tenant. This step inserts unique translation Ids for the selected applications into the target tenant.
  7. Repeat steps 1-3 if you need to translate the application into another language.
  8. Re-Import
  • Re-import the resulting file to create a new language option in the development tenant.
  • Re-Import the resulting file to create a new language option in TEST or PRODUCTION Tenant as Translation Ids are already inserted as part of package installation. New translation language import works only for those translation ids that match in the given CSV.

Notepad.png

Note: Up to 5 translated languages can be included while packaging. Exceeding 5 is known to cause performance concerns with package installation.

About Elements in the Translation Workbench

Each language translation file contains these elements:

  • Language
  • English (Default)
  • Other languages, as available
  • Element
  • Type (of Element)
  • Subtype (of Element)


Eligible Platform Elements

To view translation entries, you choose Language, Element, type, and subtype, where the type and subtype options depend on the Element.

Translationworkbench.jpg

For each item, the following information is shown:

  • Name
  • Elements (Optional)
  • Default Display Label
  • Translated Display Label
  • Default Display Label (Plural), Translated Display Label (Plural) (Optional)

Types and Subtypes

Element Type, Subtype
Actions Objects
Applications
Custom Labels Category
  • Category Name
Enumerated Fields
for:
  • Checkboxes
  • Multiple Checkboxes
  • Picklists
  • Dependent Picklists
  • Multi Select Picklists
  • Radio Buttons
Objects
Fields Objects
Field Help Labels Objects
Forms Objects
Form Related Items Objects
Sub Type
  • Layout Field Help Labels
  • Multi Value Lookup Labels
  • Quick Links
  • Related Information Section
  • Related Information Button Labels
  • Sections
Global Picklists Global Picklist
Dashboards Applications
  • Label
  • Widget Title
  • Pages
Objects
Report Folders
Reports
Sidebar
  • Label
  • Widget Title
  • Sidebars
Validation Objects
Views View Type
  • Object Related Views
  • Objects
  • Other Views
Web Tabs
  • Label
  • Widget Title
  • Sidebars

Custom Labels

Custom Labels provide the the ability to create free-form messages, or alphanumeric text strings in:

  • Onscreen help or tips
  • Alert messages
  • Warning messages

The custom labels are added via the Translation Workbench, and are used in these elements in the platform:

To add custom labels:

  1. Click GearIcon.png > Administration > Account Management > Translation Workbench
  2. Specify the following information:
    Language
    Select the desired language
    Elements
    Custom Labels
    Category
    --New Category--
    Category Name
    Enter a name for the category
  3. Click the [New Category] button
  4. In the form that appears, enter the token and the Translated Custom Message
    • A maximum of 100 tokens can be created for each Category
  5. Click [Save]

Custom Labels For Developers

Accessing a Custom Label in JAVA

The translateToken API accesses a Custom Label (a message) defined in the Translation Workbench.

Syntax
String result = Functions.translateToken(String key) 
String result = Functions.translateToken(String key, String [] args)
Parameters
key
The category and token (index key) for the message to retrieve, in the form: "#category.token_name".
args
An array of string-arguments to be substituted into the message, in the locations defined by the message format.
Returns
A string containing the selected message in the user's currently active language, with specified arguments substituted.
Example
In this example, go_msg is a Custom Label in the Translation Workbench created in the "custom" category, where the translation in the user's current language is "It's a {1} day for a {2}." Supplying the arguments then allows for variations on the message.
String [] args = {"nice", "walk"};
String msg = Functions.translateToken("#custom.go_msg", args));
    // ==> "It's a nice day for a walk."


Accessing a Custom Label in HTML

In HTML:

  • The category and tokens defined in Custom Labels are used to construct a key.
  • The key and related arguments are passed to a Message Tag, which returns a localized message.

Creating a Key

To access a Custom Label in HTML, you create a key, using the same format as Template Variables:

A category name, followed by '.' and a message or label identifier (a "token").
Example: #categoryname.tokenname

where
categoryname
Name of the Category
tokenname
Name of the Token
Example

For a category named webtab, create the following tokens:

welcome_msg = Welcome to the {0}
message = This application keeps track of your customer service requests quickly and easily

To create language labels using the custom label key, add arguments as follows:

{#webtab.welcome_msg^ABC}
Which displays in the UI as: Welcome to the ABC
Considerations
  • The carat (^) character is used to separate arguments passed to the function
  • If the argument is missing ({#webtab.message}), the default message is displayed: This application keeps track of your customer service requests quickly and easily.
  • Tokens are supported in:
  • HTML
  • Raw HTML
Example
<html>
  <head>
    <title></title>
  </head>

  <body>

    <h1>{#webtab.welcom_msg^ABC}</h1>

    <p>{#webtab.messge}</p>
   
  </body>
</html>

Using Message Tags

Message Tags support multiple languages, using Custom Labels created in the Translation Workbench.

  • When a message tag is implemented, the message appears in the user's selected language.
  • Message tags are part of the platform Tag library
Syntax
<%@ taglib uri="/LJTagLib" prefix="lj" %>
<lj:message key="#{category}.{token}" arg1="Julia" arg2="Jones"/>
Example

Assume the following item is specified in the Translation Workbench:

Category webtab
Token message
Message Requester Name: {1}, {0}

Then this code:

<%@ taglib uri="/LJTagLib" prefix="lj" %>
<html>
    <head>
        <title>Customer Details</title>
    </head>
    <body>
        <h1>Customer Details</h1>
           <p>All the details</p>
        <lj:message key="#webtab.message" arg1="Julia" arg2="Jones"/> 
    </body>
</html>

Causes this text to be inserted into the HTML:

Requester Name: Jones, Julia