Difference between revisions of "Orion/Internationalization"

Revision as of 09:33, 18 April 2012

This page is a hub for resources relating to preparing Orion for use in other languages and locales (also known by the abbreviation i18n). This work involves translating strings into other languages (often called NLS for Natural Language Support), handling bi-directional text (BIDI), and preparing content such as dates and times in a format appropriate for a given locale.

Client - adding new messages file

We are using i18n plugin of RequireJS, but to make our messages consumed by Babel we need to follow some extra rules. If you want to create a new messages file you need to add an "nls" directory with a given file structure:

nls/
   messages.js
   root/
      messages.js

Instead of "messages.js" we may use a different file name, but both *.js files need to have the same name.

The nls/messages.js file in the master file. It contains code and does not contain any strings for translation and will not be send for translation. This file should have format as follows:

Orion Editor does not have dependency to nlsutil, it should use 'orion/textview/util' import instead:

The nls/root/messages.js file is the root messages file, it contains externalized strings and is send to translation. For this reason it is very important that it kept the format as follows:

Client - using messages

To use the messages defined in the external file we should import them using i18n! prefix

Please take into account dependencies between out bundles. Editor cannot use messages from our Client, but Git client can.

In result of this import messages variable is an object containing all messages. The key of messages stay the same, but the message value is translated into a appropriate locale, if translation is available. If translation file exists, but it doesn't contain some of the messages the missing messages will be taken directly from the root translation. Those are two formats to get the message under key "Navigator":

messages.Navigator

messages.["Navigator"]

For messages containing parameters we can use dojo.substitute, but we also have more convenient helper method that is available in 'orion/util' for client bundles and in 'orion/textview/util' for editor. This is the use of the function:

mUtil.formatMessage(message, param0, param1, param2...)

The message parameter needs to be already globalized. Example use:

mUtil.formatMessage(messages.lineColumn, lineIndex + 1, offsetInLine + 1)

Orion Editor

Strings in Orion editor have already been externalized. The two files containing externalized strings are:

• web/orion/editor/nls/root/messages.js - for strings in editor
• web/orion/textview/nls/root/messages.js - for strings in text view

We also have a helper method for formatting string like "Line ${0} : Col ${1}", it can be found in orion/textview/util#formatMessage.

The editor also needs to make sure stuff like BIDI, IME, DBSC and Unicode Surrogates are all working properly. We paid some attention to these when we were first designing the editor, but there is lots of work to make the Orion editor BIDI aware to the same level of the Eclipse Desktop editor.

Plugins

Plugins globalization is different that other client files because plugins not necessarily have dependency on RequireJS.

The format of messages file is the same as described in Client globalization, but if we are not using RequireJS we don't need the master file, so the file structure would be:

nls/
   root/
      messages.js

The messages.js file format does not change.

To import the messages we should import the orion/i18n.js script apart from the orion/plugin.js. This code imports and parses the messages file:

<script type="text/javascript" src="../orion/i18n.js"></script>
<script>
  window.onload = function() {
    var messages = new eclipse.I18nMessages("nls/messages");
    alert(messages['Hello message']);
  };
</script>

The 'Hello message' will be displayed in current user locale or in the root locale if translation is not available. Also helper function messages.formatMessage is available for formatting messages with parameters.

Server

Most server strings are not currently externalized, but could easily be done using current Equinox API. The easy case is single language servers, where the natural language is provided when the server starts and it never changes. More complex would be multi-language servers where each request can have a different language and server uses the HTTP Accept-Language header to determine response language for that request. Equinox has not come up with a performant way to do this (see bug 226340), and any prerequisite dependencies such as org.eclipse.* libraries won't support it.