Overview

The translation set object is an out-of-the-box way for developers to easily create and translate multi-lingual applications. A translation set is made up translation strings, which are individual collections of values translated into multiple languages, along with the necessary contextual information for developers or translators. Translation strings can be used in interfaces and expression rules throughout an application, allowing you to provide your users with the best possible experience of your apps in their preferred language.

Translation sets allow you to:

• Quickly build a new application that supports multiple languages.
• Easily add languages to an existing app.
• Efficiently manage translated content by editing a translation string once and it updating everywhere.

Terms to know

To get a better understanding of translation sets and how they work, use the following terms and definitions as a reference.

How does it work?

After you've created a translation set and translation strings, you can use the translation strings anywhere for user display text. User display text is any text that an end user would see, like instructions, labels, and tooltips. This does not include dynamic values, record data, or record type references.

When a user views an interface that uses translation strings, the translation strings will display in the logged in user’s selected locale, as long as there’s a value for that locale. Otherwise, the strings will display in the primary translation locale.

Properties

Both the translation set object and the translation strings have properties.

Translation set properties

Translation string properties

Create and edit a translation set object

Creating and editing translation sets is simple and can be done from multiple places, so that you can make and manage a translation set without breaking your development flow.

Create a translation set

You can create a translation set object in three places: the Build view, within an interface, or anywhere with an expression editor.

In the Build view:

1. Click New, then Translation Set.
2. Configure the translation set properties:

   Property	Value
   Name	The name of the translation set.
   Translation locales	Select supported system locale to translate your translation strings into.
   Primary Translation Locale	Select a supported system locale to use as the default translation locale for the translation set and translation strings.
   Description	(Optional) A description of the translation set.

3. Click CREATE.
4. Set security and click SAVE.

You can also create a new translation set object from within an interface in either expression or design mode while creating new translation strings.

Edit a translation set

You can edit translation set properties in the Build view of your app and in the object. When editing the properties, you can add or remove translation locales, as well as change the primary translation locale.

To edit the translation set properties from the Build view, select the translation set and click PROPERTIES in the More menu.

To edit the translation set properties in the object, click PROPERTIES in the gear menu.

Inside the translation set object, you can create and manage not only your translation set, but your translation strings.

The following image highlights the actions that you can take from the translation set object:

Each translation set can contain up to 1,500 strings. If you need more than 1,500 strings in your application, create a new translation set.

Create translation strings

Translation strings are a collection of values for each translation locale that will be translated and used throughout your application. You can create translation strings in three places: the translation set object, within an interface, or within any expression editor.

Create translation strings in the translation set object

To create translation strings directly from the translation set object:

1. Click Add String.
2. Configure the translation string properties:

   Property	Value
   Value	Enter a value for the primary translation locale.
   Description	(Optional) Add a description of the translation string for developers to know which translation string to use while developing an application.
   Notes for Translator	(Optional) Add context about the translation string for translators so that they can fully understand what they are translating.

3. To add values for other translation locales, click Add value in another locale.
4. Click ADD.

Create translation strings in an interface or expression

You can create translation strings individually or in bulk from within an interface in either expression or design mode. You can create translation strings as you develop your interface or create translation strings from text in an existing interface. While creating a new string, you must include a value for the primary translation locale, but you can optionally add values in the other translation locales enabled in your translation set.

Create individual translation strings

Creating translation strings individually makes it easy to update an existing interface or make updates to expressions throughout your app.

To create individual translation strings directly in an interface in EXPRESSION mode or in any expression editor:

1. Find the user display text that you want to add as a new translation string and highlight the parameter value.

2. In the toolbar of the expression editor, click Add Translation String.

   

3. In the Translation Set field, enter a translation set or create a new translation set. If you already have a translation set created in your application, it will be auto-populated in this field.

4. Configure the translation string properties:

   Property	Value
   Value	The text that you highlighted is auto-populated as the value of your primary translation locale.
   Description	(Optional) Add a description of the translation string for developers to know which translation string to use while developing an application.
   Notes for Translator	(Optional) Add context about the translation string for translators so that they can fully understand what they are translating.

5. To add values in other translation locales, click Add value in another locale.
6. Click ADD.

Follow these same steps to create an individual translation string from an expression rule or any object with an expression editor.

To create individual translation strings from an interface in DESIGN mode:

1. Click on the component with the user display text that you want to add as a new translation string.
2. In the COMPONENT CONFIGURATION pane, hover over the property you want to translate, then click Add Translation String.
3. In the Translation Set field, enter a translation set or create a new translation set. If you already have a translation set created in your application, it will be auto-populated in this field.
4. Configure the translation string properties:

   Property	Value
   Value	The text that you highlighted is auto-populated as the value of your primary translation locale.
   Description	(Optional) Add a description of the translation string for developers to know which translation string to use while developing an application.
   Notes for Translator	(Optional) Add context about the translation string for translators so that they can fully understand what they are translating.

5. To add values in other translation locales, click Add value in another locale.
6. Click ADD.

Create a new translation set while creating translation strings

You can create a new translation set while creating new translation strings the same way from both expression and design modes of an interface, as well as in any expression editor.

To create a new translation set while creating new translation strings:

1. From the Add Translation String dialog, click + Create Translation Set in the Translation Set field.
2. Configure the translation set properties and click CREATE.
3. Set security and click SAVE.

Create translation strings in bulk

Creating multiple translation strings at once allows you to quickly take the user display text in an interface and turn it into translation strings in just a few clicks. This is great for developing new apps and interfaces.

When you generate translation strings from interface text, we collect all of the user display text, like instructions, labels, and tooltips, and create a list of values for you to review and add as translation strings. This can be done from both design and expression modes in an interface and is a great way to generate translation strings from all of the interface's user display text. You can generate up to 50 translation strings at one time and generate translation strings as many times as needed.

To generate translation strings from interface text:

1. In the toolbar of your interface, click Generate translation strings from interface.
2. In the Translation Set field, enter a translation set or create a new translation set. If you already have a translation set created in your application, it will be auto-populated in this field.
3. (Optional) Add a Description or Notes for Translator.
4. Click GENERATE, then click SAVE CHANGES.

Editing translation strings in an interface

Editing a translation string can be done in the same three places that they can be created; the translation set object, an interface, and an expression rule.

To edit a translation string in the translation set object:

1. Simply click the three dots beside the string and click Edit.

To edit a translation string from EXPRESSION mode in an interface or from any expression editor:

1. Use cmd+click on the translation string to open the Translation String dialog.
2. Edit the translation string and click SAVE.

To edit a translation string from DESIGN mode:

1. Click on the component that contains the translation string that you want to edit.

2. In the COMPONENT CONFIGURATION pane, click the translation string. This opens an expression editor dialog.

   

3. Use cmd+click on the translation string to open the Translation String dialog.
4. Edit the translation string and click SAVE.
5. Click OK to exit the expression editor dialog.

Exporting and importing translation strings as Excel file

Once you've added translation strings to your translation set, you can export the entire translation set or a subset of translation strings as a Microsoft Excel file. This allows your translators to quickly and easily provide translations using a familiar workflow. Once you've downloaded the Excel file, you can edit the file to add translated values to your translation locales, add new translation strings, or even add a new translation locales. Then, you can upload the Excel file and import the updated translation strings directly to your translation set.

Exporting translation strings for translation

To export a translation set or a selection of translation strings as an Excel file:

1. Open the translation set object.
2. (Optional) Select specific columns or translation strings to export.
   • To export only some columns or locales click COLUMNS and select the translation locales and details to export with your translation strings. Click DONE.
   • To export only the translation strings that match your filter criteria, click FILTERS and select the desired filters. Click DONE.
   • To export the entire translation set, make sure all columns and are selected and no filters are applied.
3. Click EXPORT STRINGS. Only the columns and rows shown in the grid are Exported.

You can then open and edit the file in any spreadsheet program.

Editing the translation file

When editing the translation file you can add translated values for existing translation strings, add new translation strings, and add new translation locales to your translation set. Then, your edits are reflected in the translation strings and translation set after you import the translation file.

If you've added new translation strings or a translation locale to your Excel file, you will see an informational message when you import the file letting you know that new translation strings or translation locales will be added to your translation set. No further action is required.

Updating translation locale values in an Excel file

You can easily add translations for many translation strings at once by adding translation locales values in the translation file.

To add new translations to your translation strings,

1. In the Excel file, add the translated values for each translation string to the appropriate translation locale columns.
2. Save the file.

To learn how to add these to your translation set via import, see importing the file to the translation set.

Adding new translation strings in an Excel file

To add new translation strings through an Excel file:

1. In your Excel file, add a new row.
2. Leave the UUID blank. When you import the new translation string, Appian will assign the translation string a UUID.
3. Enter a value for the primary translation locale.
4. (Optional) Enter a value for any of the additional columns.
5. Save the file.

To learn how to add these to your translation set via import, see importing the file to the translation set.

Adding translation locales in an Excel file

To add a translation locale to your translation set through an Excel file:

1. In your Excel file, add a new column. This must be after the UUID column.
2. Enter a translation locale that is enabled in your environment.
3. Enter at least one value in the new locale column.
4. When you import the Excel file, confirm the locale of the new column using the locale selection.
5. Save the file.

To learn how to add these to your translation set via import, see importing the file to the translation set.

Importing updated translation strings

To import an Excel file of updated translation strings to your translation set:

1. In the translation set object, click IMPORT STRINGS.
2. Upload a translation set file in .xls or .xlsx format.
3. Review the preview of the file and, if needed, make any changes to match the columns from the file with the columns in the translation set.
4. Click IMPORT. Do not leave or refresh the page while the import is in progress.

Testing translation strings in an interface

To test how your translation strings appear in different languages throughout your interfaces:

1. Click your user profile photo in the header bar of Appian Designer.
2. Click Settings.
3. Under Locale, change your user locale to one of the locales in your translation set that has values for the translation strings in your interface.
4. Click SAVE CHANGES.
5. Refresh your browser.
6. View and test your interfaces in the new translation locale.

Remember to change the user setting back once you're done testing.

Design best practices

While creating multi-lingual applications is largely the same as developing any other application in Appian, there are a few best practices to keep in mind while designing your interfaces, expressions, and applications so that they work optimally with the translation set object.

General best practices

• For more streamlined organization, we recommend that you only use one translation set per application.
• Use the Notes for Translator field to provide necessary context for your translators, including context to alert them to the difference in seemingly duplicate translation strings, where one word in one language can translate to multiple different words in another language.
• Note that translation sets are not currently supported for Offline Mobile.

Working with translation locales

• Ensure that the locales in your translation set are enabled as system locales in your environment and on any environment that the translation set will be used. If not, you won't be able to view the translation strings for those locales in your interfaces or application.
• Don't use the Always override users’ selected locale option in the Admin console. If this option is selected, all users will see all interface text displayed to end users in the primary system locale, regardless of their preferred locale.
• To switch to a new primary translation locale after you have created translation strings, make sure that each translation string has a value for the new primary translation locale. You won't be able to use this locale as the primary translation locale until all translation strings have a value for that locale.

Generating multiple translation strings

• When generating multiple translation strings at a time, review the suggested translation strings to make sure there are no unnecessary duplicates.
• Translation strings can't contain leading and trailing spaces. These may be included in the text that is collected when generating translation strings from interface text, but they will not be included in the translation string once it is saved to the translation set.

Using dynamic values with translation strings

Keep in mind that translation strings can't contain dynamic values, which are any value that change based on a variable, function, rule input, or record data.

To use dynamic values with your translation string, separate the value from the translation string, such as putting it directly before or after the translation string. If you try to include a dynamic value in the value of a translation string or put a dynamic value in between two separate translation strings, the word order and sentence may not make sense when translated into another language.

Example: separating dynamic values from translation strings

For example, you might want to use a date function to calculate a due date and a record type field reference to show the assigned user in an interface that uses translation strings.

An easy way to do this is to make the labels and rich text translation strings. Then, separate the dynamic values made of record type field references and date functions in the reviewer and review deadline fields from the translation strings so that they can be correctly formatted across multiple languages.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
  a!sectionLayout(
    label: translation!reviewDetails,
    contents: {
      a!richTextDisplayField(
        labelPosition: "COLLAPSED",
        value: translation!The item has been sent for review,
      ),
      a!textField(
        label: translation!reviewer,
        labelPosition: "JUSTIFIED",
        value: recordType!Order.fields.reviewer,
        readOnly: true,
      ),
      a!textField(
        label: translation!reviewer deadline,
        labelPosition: "JUSTIFIED",
        value: {
         a!addDateTime(
           startDateTime: datetime(recordType!Order.fields.orderDate),
           months: 1
         )
        },
        readOnly: true,
      )
    }
  )
}

Record type field references and translation string references are specific to each environment. This example is for reference only and will not work if you copy and paste it into your environment.

Example: issues with including dynamic values in a translation string

To show how word order can change depending on the language and how including dynamic values in (or in between two) translation strings can interfere with translation, let's translate an order update notification from English to Spanish.

In English, the notification message without dynamic values is: "The orders were sent successfully."

Translated into Spanish, this same message is: "Se mando las ordenes exitosamente."

If you tried to add in dynamic values into the translation string for the number of orders and the item ordered, your message would look something like this in English:

"The three paper orders were sent successfully."

Coded, this would look like:

The local!numberOfOrders locale!orderType orders were sent successfully.

If you tried to translate this into Spanish, the order of the words and dynamic values would be incorrect. It would render like this:

"Las tres papel ordenes se mando exitosamente."

But, the correct translation is:

"Se mando las tres ordenes de papel exitosamente."

Notice the difference in word order from the first Spanish translation to the second.

Including dynamic values in translation strings or putting them directly between two translation strings to make a sentence not only makes it hard to translate, but can lead to mistranslations and grammatical mistakes.

Security

The security role map of a translation set controls which developers can see or modify it and its properties.

Translation set object security role map

The following table outlines the actions that can be completed for each permission level in a translation set's security role map:

How translation set permissions work with other object security

The following table shows how different levels of object permissions can effect how you interact with translation string references in interfaces and other objects that reference a translation string.

Deployment

Like other Appian objects, translation sets and translation strings can be deployed to new environments in apps and packages.

When deploying to a target environment, keep in mind that deleting strings in the source environment does not impact those strings in the target environment. For example, if some translation strings that you are importing have been deleted from the source environment, but still exist in the target environment, these strings will not be deleted in the target environment.

Translation string versioning

Each time you make changes to a translation string, a new version of the translation string is created. All objects that use the translation string will automatically use the new version. This kind of allows you to easily recover earlier versions of the translation string or compare changes between versions.