Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 8 Next »

I18n (internationalization)

Icon

This page gives guidelines to I18n for:

  • Plugin developers who would like to apply the I18n mechanism in their own plugin, so that this plugin can be available in several languages
  • People who would like to help the Sonar community by making the Sonar core platform available in a new language

Sonar and the Sonar Plugins

Although the basics of the I18n mechanism are the same for every part of the Sonar ecosystem, the packaging differs if you want to apply this i18n mechanism to the Sonar core platform or to one Sonar plugin:

  • Making the Sonar core platform available in a new language requires to develop and publish a new Sonar Language Pack plugin. By default, Sonar embeds the "I18n English Pack" plugin. All other Language Pack plugins, like the "I18n French Pack" plugin, are hosted in the Sonar Plugin forge (https://svn.codehaus.org/sonar-plugins/trunk/i18n/), are maintained by the Sonar community and are available through the Sonar update center.
  • This is different for Sonar Plugins, each Sonar plugin is in charge to embed its own translations. Of course supporting i18n mechanism is not mandatory for a plugin but in that case the plugin will only be available in the default development language.

To sum up

Icon
  • Sonar platform relies on plugins to get translations
  • Sonar plugins embed by themselves all the translations they need

Sonar I18n main principles

The LanguagePack extension point

Sonar I18n mechanism relies on the LanguagePack extension point, implementing this LanguagePack is the first mandatory step.

Here is for instance the EnglishPack class of the Sonar platform:

We can see that:

  • Only one language is available: English
  • Translation is provided for three core plugins : sonar-core-plugin, sonar-design-plugin and sonar-squid-java-plugin. Those plugin keys are mandatories to be able to retrieve translation files.

The translation files

Icon

To better understand the following concepts, we're going to use the sonar-i18n-fr-plugin.

There are 2 kind of files that are used to get I18n translations:

  • Properties files
    • These are regular properties files with key/value pairs where you will put most I18n translations
    • These files must be stored in the "src/main/resources/org/sonar/i18n" directory
    • The name of these files must respect the following convention : 
      Unknown macro: {plugin_key}

      _

      Unknown macro: {language}

      .properties

        • Just for reminder, it is possible to pass arguments to the translated string. Such an entry would look like:
          mypluginkey.a_key=This is a message with 2 params: the first "{0}" and the second "{1}".
        • E.g.: the French translation for the Sonar Squid Java Plugin is "src/main/resources/org/sonar/i18n/squidjava_fr.properties"
      • HTML files
        • In case of rule descriptions, which might be long and need HTML tags, translations must be put in HTML files
        • These files must be stored in the "src/main/resources/org/sonar/i18n/
      _
      Unknown macro: {language}
      /" directory
    • The name of these files must be the key of the rule they translate
    • E.g.: the French translation for the Squid Architectural Constraint rule is "src/main/resources/org/sonar/i18n/squidjava_fr/ArchitecturalConstraint.html"

Files must be encoding in UTF-8

Icon

In the Java API, properties files are supposed to be encoded in ISO-8859 charset. Without good tooling, this can be quite annoying to write translation for languages that do not fit in this charset.
This is why we deciced to encode the properties files in UTF-8, and let Maven turn them into ASCII at build time thanks to native2ascii-maven-plugin (check the French plugin POM). This makes the process of writing translations with a standard editor far easier.
HTML files must also be encoded in UTF-8.

Conventions for the I18n keys

Here are the conventions you have to know about key namings:

  • For metrics:
    • The key for their name is "metric.metric-key.name"
    • The key for their description is "metric.metric-key.description"
  • For rules:
    • The key for their name is "rule.plugin-key.rule-key.name"
    • The description is in a separate HTML file named "src/main/resources/org/sonar/i18n/plugin-key_locale/rule-key.html"
    • The key for their parameters description is "rule.plugin-key.rule-key.param.parameter-key"
  • For widgets:
    • The key for their title is "widget.widget-key.title"
    • The key for their description is "widget.widget-key.description"
    • Any other key starts with "widget.widget-key."
  • For pages:
    • The key for the name that will be shown on the left menu is "page-key.page"

For any other key that a Sonar Plugin would define for its own I18n, the key must start with : "plugin-key."

Want to contribute to I18n in Sonar?

You are a plugin developer

Here are the main steps:

  1. Implement the LanguagePack extension point :
    • #getPluginKeys() should return only the key of your plugin
    • For each language that you want to support, you should add the corresponding locale to #getLocales() method

  2. Once you've implemented this extension point, you obviously have to declare this extension in your plugin class

  3. Use the I18n mechanism in your code
    • On Java side, use the I18nManager class
    • On Ruby on Rails side, use the #message helper method to translate your text
      • message('mypluginkey.a_key')
      • message('mypluginkey.a_key', :default => 'This is the default message')
      • message('mypluginkey.a_key'), :params => [rule.name, profile.name])

  4. Add translation files into the "src/main/resources/org/sonar/i18n/" folder
    • 1 properties file per language
    • 1 folder per language if you define new rules in your plugin and you need to translate their description

  5. And finally, translate the keys within those files!

You want to create a Language Pack plugin to offer a new translation to the Sonar platform

Here are the main steps:

  1. Check out the "I18n French Pack"

  2. *Create a new plugin, let's say the "I18n Japanese Pack", where you will copy and adapt files from the "I18n French Pack"
    • Create a JapanesePack extension, where you will just change the locale (not the #getPluginKeys() method)
    • Add the "_jp" extension to all the *.properties files that you have copied
    • Add the "_jp" extension to all the folders located in the same directory as the *.properties files

  3. And finally, translate the keys within those files!
  • No labels