CodeBeamer Localization Guide

This guide is about translating CodeBeamer to another language.

Language Codes

• A language is identified by the ISO 639 2-letter language code, e.g.
  • english = en
  • german = de
  • chinese = zh
    
• A country specific variant is additionally identified by the ISO 3166 2-letter country code, e.g.
  • Simple chinese = zh_CN
  • Traditional chinese = zh_TW

Language Resource Files

Each language is defined by a set of language resource files.
Each resource file contains the language code in its name (except for the default (English) resource files).
The character encoding of all resource files must be UTF-8, except for displaytag.properties which must be ISO-8859-1.

Property Files

The property files are contained in the codebeamer distribution library and are not customizable by customers (only by distributors).
Customers can add own text resources or override default text resources via the customer specific my-ApplicationResources*.properties files (see below).

Each line in a property file consists of key= text definitions, where key is the text resource key name (do not modify the key in any way) and the translated text.

• Lines starting with # are comment lines. We suggest translating comments too.

Be careful with text that spans multiple lines. A backslash \ character at the end of the line indicates that the text continues on the next line for example this is a multi-line translation:

cb.register.message=If you have not requested/received an activation key yet, please <a href="{0}">register</a> this installation now.<br/>\
					Registration is absolutely free and you will receive an activation key via email immediately !<br/>\
					<br/>\
					Please copy the activation key from the email you receive, paste it above and click on <i>Activate</i>.<br/>

• {x

  } in texts are placeholders for dynamic content, where x is the position of the argument to substitute.
  • You can change the order of placeholders, but be very careful that this does not change the meaning of the text!
  • Do not remove placeholders.
  • If a text contains

    {x

    } placeholders, then single quotes

    '

    have a special meaning and placeholders enclosed by single quotes will not be replaced,
    e.g. '{0}' will show as {0}, whilst "{0}" will show as "abc", where abc is the value of the first argument.
  • To output a single quote in this case, you must use

    ''

    , e.g. "It

    ''

    s" will show as "It's".
  • In texts that do not contain any placeholders, a single quote is simply a single quote without special meaning.
• Only use HTML markup in texts where the original English text also contained HTML markup, and take great care not to accidentally translate HTML markup elements and URL components, e.g.
  • English: paging.all.banner=

    <div class="pagebanner">

    {0} {1} found.

    </div>

  • German: paging.all.banner=

    <div class="pagebanner">

    {0} {1} gefunden.

    </div>

    
    

Property file resources are resolved from most specific language to default language:

name_language_country.properties → name_language.properties → name.properties

If you don't know how to translate a specified resource text, remove that text definition from your translated properties file, and the system will use the default (English) text instead. This also makes it easier to compare a specific translation with the defaults, because you can simply find out which resources have not been translated (yet).

my-ApplicationResources.properties

Starting with CB-7.7, CodeBeamer also supports customer specific text resources, by adding my-ApplicationResources*.properties files to ~/CB-../tomcat/webapps/cb/WEB_INF/classes. These files are not present or empty for a default Codebeamer distribution.

Customer specific resources have precedence over default resources, so you can

• add customer specific resources, e.g. translations for customer specific tracker choice options
• override default resources, by specifying a customer specific value for a default resource name.

The same rules and naming conventions as described for ApplicationResources.properties below, also apply for my-ApplicationResources.properties.

Please only add/override language specific text resources in a customer specific file of the appropriate language, e.g. my-ApplicationResources_de.properties!

CustomApplicationResources.properties

Starting with version 20.11-LTS (Carmen) codeBeamer supports another way of overriding localization messages by customers by adding CustomApplicationResources*.properties files to /tomcat/repository/config/i18n/.

These files are not present or empty for a default codeBeamer distribution.

CustomApplicationResources have precedence over my-ApplicationResources and the default ApplicationResources files, so you can:

• add customer-specific resources, e.g. translations for customer-specific tracker choice options
• override default resources, by specifying a customer-specific value for a default resource name.

The same rules and naming conventions as described for ApplicationResources.properties below, also apply for CustomApplicationResources.properties.

Please only add/override language-specific text resources in a customer-specific file of the appropriate language, e.g. CutomApplicationResources_de.properties!

Any changes made in CustomApplicationResources*.properties files will take effect after an application restart.

ApplicationResources.properties

This is the main language resource files.
If no such file is available for a specific language, then CodeBeamer will not offer this language at all.

This file also must contain a line with: language= ISO 639 2-letter language code
and that language code must match with the language code in the file name.

Only if your localization is country specific, e.g. Traditional Chinese, you must also specify the country= ISO 3166 2-letter country code.

E.g. Simplified Chinese:
The file name must be: ApplicationResources_zh_CN.properties, and the file must contain the following properties:

language=zh

country=CN

displaytag.properties

This is an optional resource file, that contains translations for table/paging resources.
Note: Not all resources from the default displaytag.properties file need to be translated.
This is also the only file that must be encoded in ISO-8859-1. Non-ISO characters must be specified in Unicode escape syntax.

See the german translation (displaytag_de.properties) for an example.
Take care to retain the HTML markup skeleton and to translate only the HTML title attribute values and HTML tag bodies.

Wiki Page Templates

The directory ~CB/tomcat/webapps/cb/config/templates/wiki contains templates for Wiki pages.

Each file is an atomic resource and contains

• text, intertwined with
• CodeBeamer Wiki markup (see ~CB/tomcat/webapps/cb/help/WikiHelp.wki for syntax) and
• Velocity Template Language (VTL)

Be sure to only translate 'real' text and not Wiki or VTL markup elements.

The system will look up files in the order:

name_language_country.wki → name_language.wki → name.wki

user-homepage.wki

This is the template for user homepages.
This template will be used to initially create the homepage of new users, according to the user's language and country settings.
Once a user homepage exists, changing the language and/or country of a user account has no effect on the homepage.

project-homepage.wki

This is the template for project homepages.
This template will be used to initially create the homepage of new projects, according to the locale of the user that creates the project.

project-navigationbar.wki

This is the template for project navigation bars.
This template will be used to initially create the navigation bar of new projects, according to the locale of the user that creates the project.

project-trackers-homepage.wki

This is the template for project trackers pages.
This template will be used to initially create the trackers page of new projects, according to the locale of the user that creates the project.

Wiki Help Files

The directory ~CB/tomcat/webapps/cb/help contains online help files in Wiki format.

Translating these files is optional.

WikiHelp.wki

This file contains the Wiki syntax definition and Wiki plugin descriptions.

search.wki

This file contains the online help for the CodeBeamer search syntax and options.

Language Resource Bundles

All resources belonging to a localization, should be bundled in a ZIP/TAR archive called cb_language[_country].zip with the following structure:

e.g. Resource bundle for simple chinese:

• cb_zh_CN.zip
  • WEB-INF
    • classes
      • ApplicationResources_zh_CN.properties
      • [displaytag_zh_CN.properties]
  • config
    • templates
      • wiki
        • [user-homepage_zh_CN.wki]
        • ...
  • help
    • [WikiHelp_zh_CN.wki]
    • [search_zh_CN.wki]
      

• Unpack the language resource bundle in ~CB/tomcat/webapps/cb
• Restart CodeBeamer