With the release of YouTrack 5, we now provide out-of-the-box localization support for your YouTrack instance. While the original set of supported languages includes a few European languages already, we also provide the facility for you to customize YouTrack to your liking using your own favorite language and phrasing. Here’s what the process is like.
The vast majority of what you work with in YouTrack is dynamic content, i.e. the test that you have in issue summary/description fields, custom fields, saved searches, tags, etc. None of these require localization support because you can already define them in whatever language you wish. Where localization is important is in static strings, such as what text appears on the Create Issue button.
To localize YouTrack to a particular language, you should:
- Translate the standard UI strings, which are defined in property files and notication templates.
- Put the translated files into a separate directory and provide a description of your locale in this directory, too.
- Start YouTrack with a parameter pointing to the directory with the localized content.
Let’s see how this works.
Translating Property Files
First of all, download the messages.zip archive. This ZIP file contains a set of files that you can customize — its default definitions are in English. The archive contains the following:
PredefinedFields_en.properties — contains the names of predefined fields (such as summary) that ship with the YouTrack instance by default.
dynamic_en.properties — contains a further set of strings, with the difference that this set is not reloaded when pressing the Reload button or even restarting YouTrack. These should be changed only at the time when you’re switching to another language.
all_en.properties — contains a very large set of strings that make up the bulk of YouTrack localization. This is where you can change, for example, the text on the Create Issue button.
\notification_templates — this folder contains a set of HTML-esque templates where you can also customize strings related to messages that are shown.
Property files are simple UTF-8 text files with
key=value pairs. There are several special mechanisms used to translate, e.g., plural forms of numerals — for more information on this, please consult the full YouTrack Localization Guide.
Notification templates are files with
.ftl extension. Strictly speaking, they are also editable inside YouTrack itself, via Administration|Notification Templates. If you do decide to localize these, you may wish to preserve the HTML structure intract and only change the text related to the messages.
Running YouTrack with Custom Localization
When you are ready to use your new localized files, here’s the directory structure you need to set up:
- Create a directory to house your localizations, e.g.,
- Create a subdirectory with the locale name, and copy over all the files from
messages.zip into that directory. For example, you might have a directory
- Create a file called
\youtrackUK. This is where you specify the supported locale(s), and the ID must match that of your
Here’s a sample
<?xml version="1.0" encoding="UTF-8"?>
Once this is done, you need to launch YouTrack, specifying a JVM option of
jetbrains.mps.webr.i18n.custom-translations with a value referring to your custom language path (i.e.,
x:\foo\youtrackUK). How you set it depends on how you run YouTrack. For example, on Windows, you would:
- Start up a console with Administrative permissions
- Navigate to the
\bin folder in YouTrack installation directory
- In the window that opens, define the argument as
All you have to do now is restart YouTrack, then go into Settings, scroll down to System Language and choose the new language from the list:
YouTrack will apply your new language settings, and you can start using them straight away:
And one last thing…
So that’s how easy it is to customize YouTrack. And since we imagine that many of you may be interested in localizing YouTrack to one language or another, we’ve set up a GitHub repository where all such translations can be kept. So if you’ve got a translation for a particular language, simply send us a pull request and your translation will be included in the repository!