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
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:
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:
- Upload and translate these files in any software that lets you read and edit gettext translation files.
- 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:
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:
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:
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:
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 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 subdirectoryko_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 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>
- 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:
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.
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.