This help center has been deprecated and moved to a new address, please follow this link to open an active help center.

Thank you and sorry for inconvenience!



Translating YouTrack UI

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 (.po files, property files and notification templates)
  2. Put all the translated files in a directory and provide description for your locale in a 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 UI Strings

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

Translating PO Files

The archive you have downloaded contains three PO files:

  • hub-auth.po — text strings regarding various authorization messages.
  • hub-core.po — text strings for YouTrack administration UI.
  • youtrack-reports.po — text strings for YouTrack Reports UI.

To translate these UI strings:

  1. Upload and translate these files in any software tool that supports PO files.

     Make sure that to specify the language of translation in a PO file! Otherwise, YouTrack will not recognize the files as translated and will keep displaying original English strings.

  2. When translation is ready, convert each of the PO files to JSON.
    Upload your PO file here and convert it to JSON:
    https://jetbrains.github.io/web-po2json/ 
    As the result, you must get three JSON files: hub-auth.json, hub-core.json, and youtrack-reports.json.
  3. Put the translated PO files and generated JSON files to the directory with translations. The very same directory that contains property files.

Translating Property Files

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:

key=value

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:

Agile.Clone_bundle_{0}_for_project_{1}=Clone bundle {0} for project {1}

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:

DidYouMean._It_matches_{0}_issues=It matches {0} issues.
DidYouMean._It_matches_{0}_issues[one]=It matches one issue.

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:

Template.Issues={0}
Template.Issues[other]=Issues
Template.Issues[one]=Issue

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.

predefined_field.tag=tag\:pcfv|tagged as\:f
predefined_field.star=star\:sphc|watcher\:c
predefined_field.updated=updated\:spf
predefined_field.updated_by=updated by\:f|updated\:f|updater\:spf
predefined_field.commented_at=commented\:pf
predefined_field.commented_by=commenter\:fp|commented by\:f|commented\:f
predefined_field.created=created\:spf
predefined_field.resolved=resolved date\:spf
predefined_field.project=project\:spfc|in\:f|move to\:c
predefined_field.by=by\:f|reported by\:f|reporter\:spfv|created by\:f|from\:f|created\:f
predefined_field.issue=issue id\:spf
predefined_field.links=links\:spfh
predefined_field.saved_query=saved search\:pf
predefined_field.context_folder=__$context$__\:f|context\:p
predefined_field.voted_by=voted by\:f|voter\:fp
predefined_field.votes=votes\:shp
predefined_field.sort_by=sort by\:pf|order by\:f
predefined_field.has=has\:pf
predefined_field.summary=summary\:spf
predefined_field.description=description\:phf
predefined_field.comments=comments\:pvfh
predefined_field.work=work\:pc
predefined_field.code=code\:pf
predefined_field.custom=custom\:p
predefined_field.visible_to=visible to\:pcfh
predefined_field.attachments=attachments\:phf

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':

JQueryCalendarLocalization.js.first_day=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:

<localeEntry>
        <name><Your language name></name>
        <locale><locale_ID></locale>
    </localeEntry>

For example:

<?xml version="1.0" encoding="UTF-8"?>
<locales>
    <localeEntry>
        <name>Русский</name>
        <locale>ru_RU</locale>
    </localeEntry>
    <!--localeEntry>
        <name>Deutsch</name>
        <locale>de_DE</locale>
    </localeEntry-->
</locales>

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:
    java -Djetbrains.mps.webr.i18n.custom-translations=/home/vadim/youtrack-i18n -jar youtrack.jar 8080

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

Have more questions? Submit a request

Comments

Powered by Zendesk