Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Wiki Markup
{note}Available since Sonar 2.10{note}

{info: title=I18n (internationalization)}
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 community by making the platform available in a new language
{info}

{toc:outline=true}

h1. Principles

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

* Making the Sonar core platform available in a new language requires to develop and publish a new Language Pack plugin. By default Sonar embeds the English Pack. All other Language Pack plugins, like the French Pack plugin, are hosted in the plugins forge ([https://svn.codehaus.org/sonar-plugins/trunk/l10n/]), are maintained by the community and are available through Update Center (category "Localization").

* This is different for plugins, each plugin is in charge to embed its own translations. Of course supporting i18n mechanism is not mandatory for a plugin but in that case it will only be available in the default implemented language.

{tip:title=To sum up}
* *Sonar platform relies on plugins to get translations*
* *Sonar plugins embed by themselves all the translations they need*
{tip}

h1. Translation bundles 

There are 2 types of files for localized messages:

h4. Properties files
* These are regular properties files with key/value pairs where you will put most translations
* These files must be stored in the package "org.sonar.l10n" (usually in the directory src/main/resources/org/sonar/l10n)
* The name of these files must respect the convention "<plugin key>_<language>.properties", for example "technicaldebt_fr.properties"
* Messages accept arguments. Such entries would look like:
{noformat}
myplugin.foo=This is a message with 2 params: the first "{0}" and the second "{1}".
{noformat}

h4. HTML files
* They are used for rule descriptions, which might be long and need HTML tags
* These files must be stored in the package org.sonar.l10n.<plugin key>_<language>, for example org.sonar.l10n.checkstyle_fr
* The name of these files must be the key of the rule they translate
* +E.g.:+ the French description of the Squid Architectural Constraint rule is "src/main/resources/org/sonar/i18n/squidjava_fr/ArchitecturalConstraint.html"

{warning:title=UTF-8 encoding}
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.*
{warning}

h4. Naming conventions for keys

Here are the conventions you have to know about keys :

|| Key || Description || Example ||
|{{metric.<key>.name}}|Metric name|metric.ncloc=Lines of code|
|{{metric.<key>.description}}|Metric description|metric.ncloc=Non Commenting Lines of Code|
|notification.channel.<channel key>|Name of notification channel|notification.channel.EmailNotificationChannel=Email|
|notification.dispatcher.<dispatcher key>|Subscription to notification channel|notification.dispatcher.ChangesInReviewAssignedToMeOrCreatedByMe=Changes in review assigned to me or created by me|
|rule.<repository>.<key>.name|Rule name|rule.pmd.StringInstantiation.name=String Instantiation|
|rule.<repository>.<key>.param.<param key>|Description of rule parameter|rule.pmd.VariableNamingConventions.param.memberSuffix=Suffix for member variables|
|widget.<key>.name|Widget name|widget.alerts.name=Alerts|
|widget.<key>.description|Widget description|widget.alerts.description=Display project alerts|
|widget.<key>.param.<property key>|Description of widget property|widget.alerts.param.threshold=Threshold|
|widget.<key>.*|Any other widget message|widget.alerts.tooltip=Threshold is raised|
|<page key>.page|Page names shown in the left sidebar|cloud.page=Cloud|
|<page key>.*|Any other keys used in a page|cloud.size=Size|
|<plugin key>.*|Any other keys used by plugin| |


h1. How to use localized messages ?

h3. Ruby on Rails API

This API is used when implementing Ruby widgets or pages. It's really simple, a single method must be used :
{noformatcode}
message(property_key, options={})
{noformatcode}

Options are :
* {{:default}} is the default value when the property key does not exist in bundles. If it's not set, then the key itself is returned.
* {{:params}} is an array of string arguments used in the message. These arguments are referred with their index ({0}, {1}, ...)

Examples :
{noformatcode}
message('cloud.size')
message('cloud.size', :default => 'Cloud')
message('with.arguments', :params => ['First', 'Two'])
message('with.arguments', :params => ['First', 'Two'], :default => 'Not found')
{noformatcode}

h3. GWT API


h1. How to contribute

h3. How to add a language to a plugin

Simply copy and translate the English bundles : 
* standard messages : src/main/resources/org/sonar/l10n/<plugin key>_<language>.properties
* rule descriptions : src/main/resources/org/sonar/l10n/<plugin key>_<language>/*.html


h3. How to add a language to core platform

You have to create a Language Pack plugin and host it into the forge of plugins, like the [French pack|https://svn.codehaus.org/sonar-plugins/trunk/l10n/fr]. 
It's recommended copy the [English bundles|https://github.com/SonarSource/sonar/tree/master/plugins/sonar-l10n-en-plugin/src/main/resources/org/sonar/l10n] and adapt them to the new language.

The plugin must be executed in the same classloader than the English pack, so do not forget to set the property "basePlugin" to "l10nen" into the configuration of sonar-packaging-maven-plugin.