Translatable Process Templates
Introduction
Have you wanted to see messages in the Team Advisor view in a language other than English? Have you wanted the names of fields in work items to show up in your native language? After you create a project, do you want the instructions in the associated work items, dashboards and reports to be in your native language?
Rational Team Concert 1.0.1 supports translatable process templates. A translatable process template has user-visible strings packaged so that they can be translated into languages other than English. A translatable process template can be used to create a project area with translated work item workflows, reports, dashboards, process preconditions, role names, iteration names and so on.
Some of the processes that are included in Rational Team Concert are available as translatable processes here. The translatable processes are available as an early access release for those who are interested in trying them out. Although they are only in English at this point, translations can easily be added to these templates by attaching locale-specific property files.
This article describes how translatable templates work, how to use translatable templates in your repository, and how to change an existing process so that it can be translated.
Audience Statement
This article is written for a Rational Team Concert user who is interested in exploring support for non-English process templates and project areas. You should understand the basic concepts of the Process component, such as process templates, project areas, team areas, roles, preconditions and followup actions. If you have not learned about those concepts, you may want to read Getting Started with Jazz Process and Project Areas before continuing with this article.You must be a member of the JazzAdmins group in your repository to complete the steps described in this article.
A basic understanding of internationalization and translation will also help as you read this article. The “How to make existing templates translatable?” section of this article is written expressly for Rational Team Concert users who have developed a process template and want to make it translatable. If you are interested only in using templates provided by others, you may want to skip this section.
Translatable Templates
A translatable process template has user-visible strings packaged so that they can be translated into multiple languages. Multiple files can be specified, each with the strings for a certain locale. The name of each file reveals the locale of the strings it contains. For example, consider a process template that supports two locales: English (United States) and French (Canada). The template has two files attached to it, one named template_en_US.properties and one named template_fr_CA.properties. The template_en_US.properties file contains keys and English strings, like so: Easy.4=My Easy Process
The template_fr_CA.properties file contains keys and French strings.
Easy.4=Mon Processus Facile
In the xml files that define most of the process data, the strings that are in the properties are referred to by their key, prefaced with ‘%’. This picture shows what the template would look like in the process template editor of the Rational Team Concert Eclipse UI:
When a project area is created, one of the template’s supported locales must be selected. Work items, reports, dashboards and process messages for the project area and related team areas will be in the language of the chosen locale. For instance, if I created a project area with the French version of the template described above, fields in work items would have French names, reports and dashboards would have French text, and messages in the Team Advisor view would be in French.
How to Use Translatable Templates
This section describes how to obtain the preview of translatable versions of Rational Team Concert, import them into a Jazz repository and use them to create project areas.Translatable versions of the process templates included with Rational Team Concert are available for preview here. The instructions on the that page will tell you how to download the templates to your hard drive and import them into your repository. Once you have taken these steps, you will be ready to create a project area.
You can use the Jazz Server Web UI or the Rational Team Concert Eclipse client to create a project area from the template. Instructions for creating a project area in the Rational Team Concert Eclipse client are in the Online Help. As you create the project area, notice the “Filter by locale” checkbox. By default, it will be checked and only templates that support the locale of your client will be shown. If the template you imported is not shown in the list of templates, use the dropdown list by the checkbox to choose the “English (United States)” locale. (Or, you could uncheck the checkbox to show all templates).
As you explore the project area you just created, it may not look different from other project areas you’ve created in the past. This is because the strings in the template have been moved to a properties file, but they have not been translated into a different language. If you look at the process template you imported in the Process Template editor, you will see that many of the fields show up as keys instead of the familiar text. The keys are prefaced with ‘%’. Each key corresponds to an entry in the properties files described in the previous section.
How to Add Translations to a Translatable Template
The translatable templates available as previews only include English translations at this time, but you can add translations if you like. This section contains instructions for providing translations into any language.
To add a translation to a process template, you must create the correct properties file for the locale of the translated strings, add the translated strings to the file and attach the file to the template.
Before you start creating translations, read this sidebar about the format of the properties files used by process templates.
To create the correct properties file for your translations, determine the locale information for the language you will be using. You will need this to determine the name of the properties file you will create. A two letter code for the language is mandatory; you may include the two letter code for a country if you like. The format for the properties file name is template_la_CO.properties, where la is a lower-case language code and CO is an upper-case two letter country code. For instance, template_fr_CA.properties indicates that the strings in the properties file are meant for the French (Canada) locale.
Once you have determined the locale information, open the template you are going to translate in the Rational Team Concert Eclipse client process template editor. Expand the Process Attachments section and select the template.properties file. Save the file to your hard drive. Rename the file so that it includes your locale information. This will be the properties file you translate and attach to the template.
To translate the strings in the properties file, open the file in a text editor. Translate the strings that are values, but do not translate the keys. For instance, if the properties file contains this line:
Agile.4=Setup Project
replace “Setup Project” with its translation, but leave “Agile.4=” as it is.
Once you have translated all of the strings, attach the file to the template. To do this, open the template in the Rational Team Concert Eclipse client process template editor. Expand the Process Attachments section. Click the Add… button and browse to your properties file. You can use the Advanced Options section of the dialog to set the encoding for the properties file if UTF-8 is not suitable. Click the OK button to attach the file and save the process template.
The process template now supports the locale you chose. You can create a project area to test your changes.
How to Make Your Templates Translatable
This section is for template authors. If you have developed a process template that you would like to change so that it can support multiple locales, the instructions in this section will help you. If you are interested only in using process templates supplied by others, you do not need to follow the instructions in this section.
To prepare a template for translation, you need to move the user-visible strings to a properties file, replace the strings in the process template with the corresponding keys, and attach a default properties file along with properties files for any locales that the template supports.
What Strings to Move
Before we go into detail about how to move the user-visible strings, here are some pointers to help you determine which strings you will need to move. In general, replace any string that should show up in the localized language when the process template is translated. For instance, names, descriptions and summaries should be moved. Examples include:
- process name, description and summary
- role names and descriptions
- precondition names and descriptions
- followup action names and descriptions
- work item type names
- work item query names and descriptions
- workflow names
- dashboard and dashboard viewlet descriptions
In addition, these fields should be moved:
- work item aliases
- work item enumeration literals
- work item quick information titles
- work item states, actions and resolutions
- dashboard titles and categories
- dashboard viewlet titles
- the path to the process content (if your process has process content)
If you are unsure whether a string should be moved as you work with your template, you may want to look to the preview versions of translatable templates here. If a string has been replaced with a key in the preview version of a template, you probably want to move the string in your template, too.
What Strings To Leave Untranslated
This section contains examples of strings you do not want to move to a properties file.ID fields, fields with boolean values or color values, and fields that refer to other fields should not be moved to a properties file. Fields within workitem queries should not be moved.
Here are some examples of fields that should not be moved:
- process ID
- role ID
- work item type IDs
- workflow IDs within a workitemCategoryBinding
- trim values within viewlet elements
- “true” and “false”
Changing Your Template
The first step in making your template support translation is to externalize the user-visible strings by moving them to a properties file. When you have finished externalizing your template, the properties file will contain a key/value pair for each user-visible string. Since the file name does not have any locale information, the file will be the default translation for the template. This file will serve as the basis from which other language translations are derived. Also, if a particular key/value pair is not found for a particular locale, this default translation will be used. When you are ready to move user-visible strings, create a file named template.properties and open it in a text editor.
Next, open your template in the Rational Team Concert Eclipse client process template editor. Copy each string that should show up in the localized language when the process template is translated into the template.properties file, where you associate it with a key. In the template, replace the string with “%” followed by the key from the properties file. As you work, your editor will fill up with keys, like this:
Your template.properties file will start to look like this:
Once you have moved all of the strings and replaced them with keys, save the process template and the template.properties file. Expand the Process Attachments section of the process template editor. Click the Add… button and browse to your properties file. You can use the Advanced Options section of the dialog to set the encoding for the properties file if UTF-8 is not suitable. Click the OK button to attach the file and save the process template.
The final step in preparation for translation is to attach translated properties file for each locale you want to support to your template. Each locale will require a properties file named with the locale information for the locale of the translated strings it contains. The locale specific properties file for the locale of the strings in your default properties file can be empty, since the process support will automatically use the string from the default file if it does not find the key in a locale specific file. For instance, the strings in the template.properties files attached to the preview versions of the process templates shipped with Rational Team Concert are in United States English. Each template has a template.properties file and a template_en_US.properties file attached to it. The template_en_US.properties file is empty, and lets the process tooling know that the template supports the “English (United States)” locale.
For information on creating the locale specific properties files, see the “How to Add Translations to a Translatable Template” section.
To test your work, create a project area. In the creation process your template should show up with the correct locale information. When you work with the project area and its artifacts, the strings you moved to the properties file should show up just as they did before you prepared the template for translation.
Sidebar: Process Template properties format
The properties files used by process templates can contain two types of lines: comment and key/value pairs. Comment lines begin with a ‘#’. Key/value pair contain a key an ‘=’ and a value. The key can contain only letters, digits, dashes, underscores, and periods. Whitespace around the ‘=’ is acceptable.
Here are examples:
# This entire line is a commentThe Rational Team Concert process tooling can support files that are encoded with UTF-8.
myTemplate.1=foo
myTemplate.2 = bar
© Copyright 2008 IBM
Yes