Skip to end of metadata
Go to start of metadata

YouTrack provides localization for several languages major European languages (German, French, Russian, Spanish) out-of-the-box. While being a good start, the five supported out-of-the-box languages of course do not cover all the possible localizations that you, our users, would like to have.
To give you an opportunity to have YouTrack speaking your favourite language, we have also implemented support for custom translations of UI texts.
This document will help you in localising your tracker.

Custom Localization Repository
Before we begin take a look at our YouTrack Custom Localization Repository for somebody might already localized YouTrack to your language. We have created GitHub repository to collect custom translations of YouTrack UI texts, created by our users, and to share them with the community.
For more details, please refer to the Custom YouTrack Localization Repository documentation page.

Localization Procedure Overview

YouTrack's UI has static and dynamic text strings. By dynamic strings we mean issue field names, values, tags, saved search names, etc. These strings can be translated even now, as long as we do not apply any restrictions to used languages. Of course, translated dynamic texts are just a small part and cannot be regarded as localization.

To get YouTrack localized to your language, basically, you should:

  1. Translate standard UI strings (property files and notification templates)
  2. Put all the translated files in a directory and provide description for your locale in specific file in this directory.
  3. Start YouTrack with a parameter pointing to the directory with your translated content.

Let's dive into more details.

Translating Property Files

The main part of localization is translating various default texts displayed in UI. We provide users with messages.zip archive containing three files with properties and a folder with ftl notification templates.
Files with properties are:

  • PredefinedFields_en.properties — the file contains so called "pre-defined issue fields and commands" text strings (for example, star, vote, )they need attention about flags and multiple variations depending on usage.
  • dynamic_en.properties — these are the text strings that are not reloaded when pressing reload button and even on YouTrack restart. They should be changed only when explicitly switching to another language. In such case after YouTrack restart they will be used when changing language.
  • all_en.properties — all other messages. Reload messages works.

Please note that all translations should be in UTF-8 character encoding!

Format of Property Files

As in any regular property file, a property is defined by a property ID and the actual value (string) that will be used for this identifier. Plus, any line that starts with '#' (hash mark) is a comment which will be ignored while processing.

In more formal way, each property is described in the following format:

where key is a unique identifier of a property, and the value is the string that should be localized. A string can contain substrings like {0} or {1}, which represent macros that will be replaced by some value while running the application. For example:

Here the {0} macros will be replaced with the name of a bundle, and the {1} macros will be replaced with the name of a project.

Please note that any such macros found in the original string should be preserved in the localized version of the same string!

Translating Plural Forms

One of the biggest difficulties in internationalization is translating and adapting to your language various plural word forms. In English, there are two forms — singular and plural, but some languages have more plural forms depending on count, and some languages even have none plural forms. For example, for English language, we have such strings for different forms:

In YouTrack localization, we based localization rules for plural forms on Google Web Toolkit (GWT) implementation for internationalization of plural forms, which provide for each language a set of identifiers for distinguishing various plural forms. Each language has identifier 'other'.

To be more specific, for the languages that we plan to provide out-of-the-box with the release, we use the following identifiers:

  1. English, Deutsch:
    • one - for the singular form (for 1),
    • other — for any other case.
  2. French:
    • one — for singular (0 and 1);
    • other — for any other case
  3. Russian:
    • one — a number ending with '1' except '11' and those ending with '11';
    • few — for numbers ending with 2,3,4 except 12-14 and those ending with 12,13,14;
    • other — for any other case.

For any language, you can have a translation with 'main' ID (without additional singular or plural specific identifier provided in brackets), and add another translated string after the main one with the additional identifier, if there is a case where translation depends on a number not placed in the string. For example:

Translating Predefined Fields Properties

The PredefinedFields_en.properties file contains so called "pre-defined issue fields and commands" text strings (for example, star, vote, watcher, etc.), which can have multiple variations depending on usage. That is, text presentation of these attributes in UI depends on the current context the attribute is mentioned in. For each case the attribute is presented in specific form, which is denoted by a flag.
For example, one issue attribute "tag" is shown as 'tag' in most cases (issue attributes, commands, and search request keyword), but also can be addressed as "tagged as:" keyword in search request.

Each attribute can have several forms. For each attribute, forms are presented in the <attribute text string>:form flag(s) format and separated with "|".

Form flag is denoted by a single latin letter and must not be translated! Each <attribute text string> should be translated. If needed, some forms separated by "|" can be removed or added. But if a flag follows at least one form in original English string, then at least one form with this flag must be presented in the localized version, and vice versa. Please note, there should be no extra flags in localization.

Meaning of the flags:

  • p: presentation, this is the main field name
  • s: sort, this form is used when user wants search results to be sorted by this field, it is appended after "sort by:" ("sort by: votes", "sort by: resolved date"). "Sort by" itself is a field of the same flavour, it has id "predefined_field.sort_by".
  • f: filter, this form is used when the field is used as a search criteria. For example: "tag: some_tag" or "tagged as: another_tag", "summary: some text to search in summary", "resolved date: 2013-04".
  • h: has, this form is used when searching for issues that have some attribute. For example, "has: star", "has: comments". "Has" itself is also a predefined field with id "predefined_field.has".
  • c: command, this form is used when setting the field using command line. Commands look like: "tag: some_tag", "project: JT"
  • v: visibility, this is displayed near checkbox which controls if this field should be shown on issue list.

Setting the First Day of Week

For different localizations a week can start either from Sunday or from Monday.

This settings is controlled by JQueryCalendarLocalization.js.first_day property, which can be find in the all_<locale>.properties file.

By default, it is set to '0', meaning that weeks start with Sunday. If you want weeks start with Monday, then set the property to '1':

Translating Notification Templates

Notification templates use ftl-files as the basic blocks that form templates. You can view the list of all available ftl-files in the Administration > Notification templates page.

As you probably know, you can not only view the list of available templates but also edit them right there, in the interface. If so, you can rightfully ask us, why do need to translate these templates in some file and then put it in a proper place for localization, as long as you can translate them right there, in place. The answer is easy, if you decide to revert your changes and restore the default version after some changes, you will get the default

To localize these files you should translate content, as you would translate a regular HTML file - all the meaningful texts except the tags. Also, you should translate those attributes of the tags that are used in UI, for example, content of 'title' attribute.

Running YouTrack with the Custom Localization

When the translation is ready, you should add your custom locale to the supportedLocales.xml file in the following format:

For example:

To start YouTrack with the brand-new translated UI:

  1. Check that your custom translated files are put in the correct directory with the <locale_ID> name.
  2. Run YouTrack with the Java machine parameter jetbrains.mps.webr.i18n.custom-translations, which points to the folder with custom localized files.
    For example, if you run YouTrack as JAR file from the command line, the command should look something like this:

If you run YouTrack as service on Windows or Unix-like OS, or as WAR in your custom servlet container, you must specify the jetbrains.mps.webr.i18n.custom-translations parameter in your Java machine properties.

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.