YouTrack Standalone 7.0 Help

Language SupportCustom Localization Repository

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 have implemented support for custom translations of the YouTrack user interface.
This tutorial shows you how to localize your tracker.

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. Set the First Day of the Week — if the first day of the week in your locale is a Monday, change the setting for the first day of the week.
  5. Translate Notification Templates — translate the text used in notifications.
  6. Copy Translated Files to Your YouTrack Server — copy the translated files to a new directory on your YouTrack server.
  7. Add the Custom Locale to YouTrack — add your custom localization to the list of supported languages for your YouTrack server.
  8. Enable Right-to-Left Language Support — if your custom localization reads from right to left, enable RTL language support.
  9. 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:

FileDescription
hub-auth.poContains text strings that are displayed for various authorization messages.
hub-core.poContains text strings that are shown on the administration pages in YouTrack.
youtrack-reports.poContains text strings that are shown in the Reports section of YouTrack.

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:

FileDescription
PredefinedFields_en.propertiesThis 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.propertiesThis 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.propertiesThis 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:

LanguageIdentifierUsage
English, GermanoneSingular forms (1)
otherAll other cases
FrenchoneSingular forms (0 and 1)
otherAll other cases
RussianoneNumbers that end with with 1 except 11 and other numbers that end in 11.
fewNumbers that end with 2, 3, and 4 excpet 12-14 and numbers that end with 12, 13, and 14.
otherAll 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:

FlagMeaningDescription
pPresentationThis is the primary name of the field.
sSortThis 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.
fFilterThis 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.
hHasThis 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".
cCommandThis is the form of the word that is used when setting the field using command line. Commands look like: "tag: some_tag", "project: JT"
vVisibilityThis 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

Set the First Day of the Week

Monday is the first day of the week according to the international standard ISO 8601, but in the US, Canada, and Japan it's counted as the second day of the week.

This setting is controlled by the JQueryCalendarLocalization.js.first_day property. The default value for this setting is 0, meaning that weeks start with Sunday. The source language in the messages.zip archive is English (US). This property is not set in the source property file.

To set Monday as the first day of the week for your locale, add this property to the all_<country code>.properties and set the value to 1. For example:

JQueryCalendarLocalization.js.first_day=1

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. Locate the folder that stores localization files on your server. Search for the following directory:
    YouTrack\webapps\ROOT\WEB-INF\classes\translations
  2. Add a folder to the translations directory 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, the directory is named as follows:
    ko_KR
  3. Copy all of your translation files to the new directory. The directory should include all of the following files:
    TypeFilename
    PO Translationhub-auth
    hub-core
    youtrack-reports
    JSONhub-auth.json
    hub-core.json
    youtrack-reports.json
    Propertiesall_<language code>
    dynamic_<language code>
    PredefinedFields_<language code>
  4. Copy the notification_templates directory that contains your localized notification templates to the directory for your localization.

Add the Custom Locale to YouTrack

When you have copied all of the files to your YouTrack server, add your custom locale to the list of supported locales in YouTrack. Add your locale to the supportedLocales.xml file that is stored in the translations directory the following format:

<localeEntry> <name><Your language name></name> <locale><language code_country code></locale> </localeEntry>

For example:

<?xml version="1.0" encoding="UTF-8"?> <locales> <localeEntry> <name>Русский</name> <locale>ru_RU</locale> </localeEntry> <localeEntry> <name>조선어</name> <locale>ko_KR</locale> </localeEntry> </locales>

Enable Right-to-Left Language Support

If your custom localization reads from right to left, you need to 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 uploaded 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 correct directory with the <language code_country code> name.
  2. Run YouTrack with the Java machine 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-i18n -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, you must specify the jetbrains.mps.webr.i18n.custom-translations parameter in your Java machine properties.

Last modified: 2 February 2017