Translatable Process Templates in Rational Team Concert 2.0
Introduction
Are you a processs template author who wants to provide messages for the the Team Advisor view, work item fields, dashboards and reports in multiple languages? Are you interested in adding new languauge strings to existing processes? This article will explain how to do both of those things.
Rational Team Concert 2.0 ships with translated process templates. The translated process templates can be used to create project areas with work item fields, reports, dashboards, process preconditions, role names, iteration names and so on rendered one of several languages.
If you are a process template author, you can provide translations for your process templates by making them “translatable”. A translatable process template has user-visible strings packaged so that they can be translated into languages other than English. When a Rational Team Concert user creates a project area with the template, the user picks his or her preferred language. The messages in the project area will be displayed in the chosen language.This article describes how translatable templates work, how to change an existing process so that it can be translated, and how to provide translations for process templates.
Audience Statement
This article is written for a Rational Team Concert process author who is interested in providing process templates that can support multiple languages. 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 Project Areas and Process in Rational Team Concert 2.0 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.
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.messages and one named template_fr_CA.messages. The template_en_US.messages file contains keys and English strings, like so:Easy.4=My Easy Process
The template_fr_CA.messages 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 messages file are referred to by their keys, 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 Make Your Templates Translatable
If you have developed a process template that you would like to change so that it can support multiple languages, the instructions in this section will help you. If you are interested only in adding translations to process templates supplied by others, you do not need to follow the instructions in this section. You can skip to the How to Add Translations to a Translatable Template section.
To prepare a template for translation, you need to move the user-visible strings to a messages file, replace the strings in the process template with the corresponding keys, and attach a default messages file along with messages 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
If you are unsure whether a string should be moved as you work with your template, you may want to look at the templates that ship with Rational Team Concert. If a string has been replaced with a key in one of the predefined templates, 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 messages file.ID fields, fields with boolean values or color values, and fields that refer to other fields should not be moved to a messages 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 messages file. When you have finished externalizing your template, the messages 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.messages 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.messages file, where you associate it with a key. In the template, replace the string with “%” followed by the key from the messages file. As you work, your editor will fill up with keys, like this:
Your template.messages 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.messages file. Go to the Process Attachments section of the process template editor. Click the Add… button and browse to your messages file. You can use the Advanced Options section of the dialog to set the encoding for the messages file if UTF-8 is not suitable. Click the OK button to attach the file and save the process template.
The final step in translation is to attach a translated messages file for each locale you want to support to your template. Each locale will require a messages file named with the locale information for the locale of the translated strings it contains. The locale specific messages file for the locale of the strings in your default messages 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.messages files attached to the predefined process templates shipped with Rational Team Concert are in United States English. Each template has a template.messages file and a template_en_US.messages file attached to it. The template_en_US.messages file is empty, and lets the process tooling know that the template supports the “English (United States)” locale.
The next section outlines the steps for creating the locale specific messages files.
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 messages file should show up just as they did before you prepared the template for translation.
How to Add Translations to a Translatable Template
Once a template has been prepared for translation by having its strings externalized, you can add translations for one or more languages. This section contains instructions for providing translations into any language.
To add a translation to a process template, you must create the correct messages 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 messages files used by process templates.
To create the correct messages 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 messages 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 messages file name is template_la_CO.messages, where la is a lower-case language code and CO is an upper-case two letter country code. For instance, template_fr_CA.messages indicates that the strings in the messages 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. Click on the Links tab and find the the Process Attachments section. Select the template.messages file. Save the file to your hard drive. Rename the file so that it includes your locale information. This will be the messages file you translate and attach to the template.
To translate the strings in the messages file, open the file in a text editor. Translate the strings that are values, but do not translate the keys. For instance, if the messages file contains this line:
scrum_spec_4=Setup Project
replace “Setup Project” with its translation, but leave “scrum_spec_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. Click on the Links tab and find the Process Attachments section. Click the Add… button and browse to your messages file. You can use the Advanced Options section of the dialog to set the encoding for the messages 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.
Sidebar: Process Template messages format
The messages 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 comment
myTemplate.1=foo
myTemplate.2 = bar
Sidebar: Providing Process Content
Process templates in Rational Team Concert can provide extended documentation in the form of an archive of HTML files named processContent.zip. A process template’s documentation is available from any project area created with the template via a link in the project area editor:
Process template authors can attach multiple archive (zip) files to a process template to provide documentation in different languages. Each project area created from the template will be populated with the correct version of the documentation, according to the project area’s locale.
To provide a translated version of your process documentation, create a zip archive of the translated files and any items the files reference. For instance, if your translated HTML files reference images, the images must be in the zip archive with the HTML files. Name the zip archive processContent_la_CO.zip, where la is a lower-case language code and CO is an upper-case two letter country code. Attach the zip archive to your process template.
© Copyright 2008, 2009 IBM
Yes