YouTrack Standalone 2017.3 Help

Localization Tutorial

YouTrack provides localization support for English, German, French, Russian, and Spanish. While this is a good start, there are a lot of other languages out there.

To give you the chance to work with YouTrack in your language of choice, we support custom translations of the YouTrack user interface. This tutorial provides instructions for creating a custom localization from the English US source files. Custom localization from another default localization is not supported.

Keep in mind that you can customize notifications that are sent by YouTrack without localizing the user interface. The email and Jabber notifications are based on templates that you can customize system-wide or on a per-project basis. You can apply changes for a regional dialect of one of the default languages by editing the notification templates in your desired language.

Overview

The YouTrack user interface has static and dynamic text strings. By dynamic strings, we mean issue field names, values, tags, and saved search names. You can use any language you want when you create fields and enter values - YouTrack does not apply any restrictions to the input for dynamic strings. Of course, dynamic strings only make up a small part of the interface. You'll want to localize the static strings as well.

The process for localizing YouTrack in your language consists of the following steps:

  1. Download the Translation Source Files — download the source files from our localization repository.

  2. Translate Gettext Files — translate the components of the user interface that are written as gettext and saved in portable object (.po) files.

  3. Translate Property Files — translate the components of the user interface that are stored in property files.

  4. Translate Notification Templates — translate the text used in notifications.

  5. Copy Translated Files to Your YouTrack Server — copy the translated files to a new directory on your YouTrack server.

  6. Enable Right-to-Left Language Support — if your custom localization reads from right to left, enable RTL language support.

  7. Start YouTrack with Custom Localization — set the start parameters for your YouTrack instance to point to the directory with your translated content.

Download the Translation Source Files

Download the English-language source files from our localization repository in GitHub. The messages.zip archive contains all of the files that you need to localize YouTrack in your language.

Extract the files from the archive to a folder in your local directory.

Translate Gettext Files

The first set of files you want to localize are written as gettext and saved in a portable object (.po) format for translation files. The messages.zip archive contains the following portable object files:

File

Description

hub-auth.po

Contains text strings that are displayed for various authorization messages.

hub-core.po

Contains text strings that are shown on the administration pages in YouTrack.

youtrack-reports.po

Contains text strings that are shown in the Reports section of YouTrack.

One string in the youtrack-reports.po file you want to pay attention to has the source text m,h,d,w. This string is parsed to format work items for the time tracking feature. You need to localize this string in the same format. Use single characters to represent minutes, hours, days, and weeks, separated by commas.

To translate portable object files:

  1. Upload and translate these files in any software that lets you read and edit gettext translation files.
  2. When finished, convert the translated content of each portable object file to JSON. Any file you upload here is converted to JSON and downloaded to your local directory.

Translate Property Files

There are three properties files in the messages.zip archive. These files contain text strings that are shown on various parts of the YouTrack user interface:

File

Description

PredefinedFields_en.properties

This file contains text strings that are used for for pre-defined issue fields and commands. For example, "Star" and "Vote". These strings require that you pay attention to flags and provide multiple variations depending on the usage of the label.

dynamic_en.properties

This file contains the the text strings that are not reloaded when pressing the reload button or restarting the YouTrack instance. 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

This file contains all other messages. Reload messages works.

All translated property files must use UTF-8 character encoding.

Property File Format

As is the case with most property files, a property is defined by a property ID and the actual value (string) that is used for this identifier. Lines that begin with a number sign (#) are comments. Commented lines are ignored during processing.

Each property is described in the following format: key=value

  • The key is the unique identifier of a property.

  • The value is the string of text that should be localized.

A string can contain substrings like {0} or {1}. These substrings represent macros that are replaced with a value when running the application. For example:

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

In this example, the {0} macro is replaced with the name of a bundle, and the {1} macro is replaced with the name of a project.

When you localize a string that contains references to macros, the localized string should contain the same references that are found in the original string.

Translating Plural Forms

One of the biggest difficulties in localization is translating and adapting plural forms of each word. In English, there are two forms — singular and plural. Other languages have more plural forms depending on count, and some languages even have no plural forms.

For example, we have two strings for different forms in English:

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

In YouTrack localization, the localization rules for plural forms are based on the Google Web Toolkit (GWT) implementation for internationalization of plural forms. This toolkit provides a set of identifiers that distinguish various plural forms. Each language has an other identifier for pural word forms.

For the languages that we support in YouTrack, we use the following identifiers:

Language

Identifier

Usage

English, German

one

Singular forms (1)

other

All other cases

French

one

Singular forms (0 and 1)

other

All other cases

Russian

one

Numbers that end with with 1 except 11 and other numbers that end in 11.

few

Numbers that end with 2, 3, and 4 excpet 12-14 and numbers that end with 12, 13, and 14.

other

All other cases

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 Field Properties

The PredefinedFields_en.properties file contains text strings that are used for pre-defined issue fields and commands. For example, the labels for "Star", "Vote", and "Watcher". These strings can have multiple variations based on their usage. That is, text presentation of these attributes on the user interface 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 displayed as "tagged as:" when used as a keyword in a search request.

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

The form flag is represented by a single latin letter. This letter must not be translated! Each <attribute text string> should be translated. If needed, you can remove or add forms, separated by the vertical bar. If a flag follows at least one form in the original English string, then at least one form with this flag must be present in the localized version, and vice versa. The localization cannot contain additional flags that are not used in the source language.

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

The meaning of each flag is described in the following table:

Flag

Meaning

Description

p

Presentation

This is the primary name of the field.

s

Sort

This is the form of the word that is used when the user wants to sort search results by this field. This form is appended after sort by: ("sort by: votes", "sort by: resolved date"). "Sort by" itself is a field of the same type, with the "predefined_field.sort_by" ID.

f

Filter

This is the form of the word that 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 is the form of the word that 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 is the form of the word that is used when setting the field using command line. Commands look like: "tag: some_tag", "project: JT"

v

Visibility

This is the form of the word that is displayed near the checkbox that controls whether this field is shown on issue list.

When you save your translated properties, change the language part of the filename to match the ISO 639-1 language code for your localization. For example, if you localize YouTrack into Korean, the properties files are named as follows:

  • all_ko
  • dynamic_ko
  • PredefinedFields_ko

Translate Notification Templates

Notification templates use FreeMarker template (FTL) files as the basic blocks that form templates. You can view the list of available FTL files on the Administration > Notification Templates page.

As you probably know, you can not only view the list of notification templates but also edit them right there, in the interface. You can rightfully ask if you can translate the notification templates in place, why do you need to translate these templates in external files and add them to your localization package? The answer is easy. If you revert your changes and restore the default version, you get the default English text.

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

Copy Translated Files to Your YouTrack Server

When you have finished translating all of the source files, copy the files to your YouTrack server.

To copy your files to the server:

  1. Create a directory to store localization files on your server. You can assign the directory whatever name you like. For example, l10n.

  2. Add a subdirectory to store your custom localization files. Name the folder with the ISO 639-1 language code and ISO 3166-1 country code for your locale.
    For example, if you localize YouTrack for South Korea, name the subdirectory ko_KR.

    You can store more than one custom localization in the directory that stores localization files. However, you can only choose one language to use in the YouTrack user interface for your server.

  3. Copy all of your translation files to this subdirectory. The subdirectory should include all of the following files:

    Type

    Filename

    PO Translation

    hub-auth
    hub-core
    youtrack-reports

    JSON

    hub-auth.json
    hub-core.json
    youtrack-reports.json

    Properties

    all_<language code>
    dynamic_<language code>
    PredefinedFields_<language code>
  4. Copy the notification_templates directory that contains your localized notification templates to the subdirectory for your localization.

Enable Right-to-Left Language Support

If your custom localization reads from right to left, enable RTL language support for your YouTrack server. For more information, see Right-to-Left Language Support.

To enable RTL language support:

  1. Open the Administration > Global Settings page.

  2. In the System Language section, select the RTL Support option.

  3. Click the Save button at the bottom of the page.

Start YouTrack with Custom Localization

When you have translated and copied your custom localization to the server, you can start YouTrack and use the newly translated user interface.

To start YouTrack with the new localization:

  1. Check that your custom-translated files are stored in the directory with the <language code_country code> name.

  2. Run YouTrack with the Java start parameter jetbrains.mps.webr.i18n.custom-translations, which points to the folder that contains the custom localization.
    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-l10n -jar youtrack.jar 8080

    If you run YouTrack as service on either Windows, a *nix operating system, or as a WAR in your custom servlet container, set the jetbrains.mps.webr.i18n.custom-translations parameter. For instructions, see Configure JVM Options.

Last modified: 7 March 2019