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:

Download the Translation Source Files — download the source files from our localization repository.
Translate Gettext Files — translate the components of the user interface that are written as gettext and saved in portable object (.po) files.
Translate Property Files — translate the components of the user interface that are stored in property files.
Translate Notification Templates — translate the text used in notifications.
Copy Translated Files to Your YouTrack Server — copy the translated files to a new directory on your YouTrack server.
Enable Right-to-Left Language Support — if your custom localization reads from right to left, enable RTL language support.
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

The English-language source files are published to a public repository in GitHub. For each major release, we upload a messages.zip archive. This ZIP archive contains all of the files that you need to localize YouTrack in your language.

To download the source files:

Access the localization repository.
Locate the major release version that corresponds with the version of your YouTrack installation.
Click the messages.zip link.
- The messages.zip archive is downloaded to your computer.
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
`frontend.po`	Contains text strings that are shown in various locations of the YouTrack user interface.
`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-issues-widget.po`	Contains text strings that are shown in an issues widget on a YouTrack dashboard.

One string in the frontend.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:

Upload and translate these files in any software that lets you read and edit gettext translation files.
Important!

Always specify the target language in the translation file. Otherwise, YouTrack does not recognize that the files have been translated and displays the original strings in English.
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)
English, German	`other`	All other cases
French	`one`	Singular forms (0 and 1)
French	`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:

Create a directory to store localization files on your server. You can assign the directory whatever name you like. For example, l10n.
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.

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

Type	Filename
PO Translation	`frontend`
	`hub-auth`
	`hub-core`
	`youtrack-issues-widget`
JSON	`frontend.json`
	`hub-auth.json`
	`hub-core.json`
	`youtrack-issues-widget.json`
Properties	`all_<language code>`
	`dynamic_<language code>`
	`PredefinedFields_<language code>`

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:

Open the Administration > Global Settings page.
In the System Language section, select the RTL Support option.
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:

Check that your custom-translated files are stored in the directory with the <language code_country code> name.
Run YouTrack with the Java start parameter jetbrains.mps.webr.i18n.custom-translations, which points to the folder that contains the custom localization.
- 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
- For ZIP and MSI installations, set the jetbrains.mps.webr.i18n.custom-translations parameter. For instructions, see Configure JVM Options.

Last modified: 7 March 2019