Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
{info: title=I18n }
Wiki Markup
Info
titleI18n (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
  • Sonar
  • community
  • by
  • making
  • the
  • Sonar
  • core
  • platform
  • available
  • in
  • a
  • new
language {info} {toc:outline=true} h1. 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 ([
  • language
Table of Contents
outlinetrue

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.

...

:= } * *
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. Sonar I18n main principles h2. 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: {code:java}
  • 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:

Code Block
java
java
public class EnglishPack extends LanguagePack {
    public List<Locale> getLocales() {
    return Arrays.asList(Locale.ENGLISH);
  }
  public List<String> getPluginKeys() {
    return Arrays.asList("core", "design", "squidjava");
  }
}
{code}

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

Tip

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

|http://svn.codehaus.org/sonar-plugins/trunk/i18n/sonar-i18n-fr-plugin/]. {tip} 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

.

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

...

    • :

...

    • No Format

...

    • 
      {plugin_key}_{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 directory
      No Format
      
      

...

    • src/main/resources/org/sonar/i18n/{plugin_key}_{language}/

...

    • 
      

...

    • 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"

...

}
Warning
titleFiles must be encoding in UTF-8

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} h2. 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 "*

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')

...

      • Wiki Markup
        {{message('mypluginkey.a_key'), :params => \[rule.name, profile.name\])}}
        \\
        \\

...

  1. Add

...

  1. translation

...

  1. files

...

  1. into

...

  1. the

...

  1. "src/main/resources/org/sonar/i18n/"

...

  1. 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

  1. And finally,

...

  1. translate

...

  1. the

...

  1. keys

...

  1. within

...

  1. those

...

  1. files

...

  1. !

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!