Page History
...
Although the basics of the i18n mechanism are the same for every part of the ecosystem, the packaging differs depending on what you are developing:
- Translations for the Sonar PlatformSonarQube: making the Sonar Platform SonarQube available in a new language requires you to develop and publish a new Language Pack plugin.
- By default Sonar default SonarQube embeds the English Pack.
- All other Language Pack plugins (, like the French Pack plugin) , are hosted in the Plugins Forge, are maintained by the community, and are available through Update Center Marketplace (category "Localization").
- Translations for the Sonar the SonarQube Community Plugins: open-source plugins of the Sonar from the SonarQube Community (hosted in the Plugins Forge) must embed only the bundles for the default locale (en). Translations will be done in the Language Pack plugins.
- Translations for other Plugins: closed-source/commercial/independant independent plugins must embed the bundles for the default locale and the translations for every language they want to support.
Tip | ||
---|---|---|
| ||
|
Translation
...
Bundles
There are two types of files for localized messages:
Properties files
Localized messages are stored in 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
" package (usually in the directory src/main/resources/org/sonar/l10n directory) - The name names of these files must respect follow the convention "<key of the plugin to translate>_<language>.properties", for example "technicaldebtwidgetlabs_fr.properties" or "core_fr.properties" for core bundle. See sonar-packaging-maven-plugin for details on plugin key derivation.
Messages can accept arguments. Such entries would look like:
No Format myplugin.foo=This is a message with 2 params: the first "{0}" and the second "{1}".
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>"
- Starting with Sonar 3.0, the files should be stored in the package "org.sonar.l10n.<key of the plugin to translate>_<language>.rules.<repository key>" (backward compatibility is ensured for l10n plugins which use the former location)
- The name of these files must be the key of the rule they translate
- Example: the French description of the Squid Architectural Constraint rule is "src/main/resources/org/sonar/l10n/squidjava_fr/ArchitecturalConstraint.html"
- Or, starting with Sonar 3.0: "src/main/resources/org/sonar/l10n/squidjava_fr/rules/squid/ArchitecturalConstraint.html" (as "squidjava" is the plugin key and "squid" the repository key)
Warning | ||
---|---|---|
| ||
In the Java API, properties files are supposed to be encoded in ISO-8859 charset. Without good tooling, this it can be quite annoying to write translation translations for languages that do not fit in this charset. |
Naming conventions for keys
Here are the conventions you have is what you need to know about conventions for keys:
Key | Description | Example | |
---|---|---|---|
| Metric name |
| |
| Metric description |
| |
| Name of notification channel |
| |
| Subscription to notification channel |
| |
| Rule name |
| |
| Description of rule parameter |
| |
dashboard.<key>.name | Dashboard name, since 2.14. | dashboard.Hotstpots.name=Point Chauds | |
| Qualifier name, since 2.13. |
| |
| Widget name |
| |
| Widget description |
| |
widget.<key>. | paramproperty.<property key>.name | Name of widget property | widget.hotspot_most_violated_rules.property.defaultSeverity.name=Default severity |
widget.<key>.property.<property key>.desc | Description of widget property | widget. | alerts.param.threshold=Thresholdwidget.<key>.hotspot_most_violated_rules.property.defaultSeverity.desc=If selected, |
widget.<key>.property.<property>.option.<option>.name | Name of item of dropdown list | ||
| Any other widget message |
| |
| Page names shown in the left sidebar |
| |
| Any other keys used in a page |
| |
| Category name of properties, since 2.11 |
| |
property.category.<category key>.description | Short description of category of properties, since 3.6 | property.category.General.description=General properties of SonarQube | |
property.category. | Subcategory name of properties, since 3.6 | property.category.exclusions.global=Global exclusions | |
property.category. | Short description of subcategory of properties, since 3.6 | property.category.exclusions.global.description=Configuration of global exclusions | |
| Property name, since 2.11 |
| |
| Property description, since 2.11 |
| |
| Any other keys used by plugin |
|
How to
...
read localized messages
...
Ruby on Rails API
This API is used when implementing Ruby widgets or pages. It's really simple, a single method must be used :
Code Block |
---|
message(property_key, options={})
|
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 message arguments.
Examples :
Code Block |
---|
message('cloud.size')
message('cloud.size', :default => 'Cloud')
message('with.arguments', :params => ['First', 'Two'])
message('with.arguments', :params => ['First', 'Two'], :default => 'Not found')
|
Of course the Rails framework provides other formatting methods like :
Code Block |
---|
# localize dates or datetimes
l(date_or_time)
|
Java API
from a plugin extension?
The component org.sonar.api.i18n.I18n
is available for web server extensions. Batch Scanner extensions are not supported yet and can not load bundles.
...
Writing a Language Pack
A Language Pack defines bundles for the Sonar Platform and for the Sonar Community SonarQube and/or plugins.
Creating a
...
Language Pack
The easiest way to create a new pack is to copy the French Pack and to adapt it to your language.
Maintaining a Language Pack
Set In the pom file, set the versions of SonarQube and of the plugins that you want to translate in the pom file:
...
.
...
<properties>
...
<!-- Versions of the plugins translated by this language pack -->
<bundle.abacus>0.1</bundle.abacus>
<bundle.branding>0.3</bundle.branding>
<bundle.core>3.4-RC3</bundle.core>
<bundle.javasquid>1.1</bundle.javasquid>
<bundle.jira>1.0</bundle.jira>
<bundle.motionchart>1.4</bundle.motionchart>
<bundle.squidjava>1.0</bundle.squidjava>
<bundle.violationdensity>1.2</bundle.violationdensity>
...
</properties>
To check the missing key,
When it's time to update your language pack for a new version of SonarQube or a plugin, the easiest way to see what keys are missing is to run:
Code Block | ||
---|---|---|
| ||
mvn test |
...
Each time you add a new bundle or you update an existing one, please create a JIRA ticket on the corresponding L10n component in order to track changes.
...
Localizing a Plugin
This part section applies if you are developing a commercial / closed-source plugin, or an open-source plugin that is not part of the Sonar SonarSonarQube Community Plugins forge.
Such plugins If your plugin falls in this category, it must embed their its own bundles. Bundles Bundle must be added to defined in src/main/resources with the following convention names :
...
/org/sonar/l10n/<plugin key>_<language>.properties
...
- Up to Sonar 3.0: org/sonar/l10n/<plugin key>_<language>/*.html
- Since Sonar 3.0: org/sonar/l10n/<plugin key>_<language>/rules/<repository key>/*.html
The default bundle is mandatory, and must be the English translation. For example the plugin with key "mysonarplugin" must define the following files in order to enable the French translation:
org/sonar/l10n/mysonarplugin.properties
org/sonar/l10n/mysonarplugin_fr.properties