Versions Compared

Key

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

Available since Sonar 2.10

{note} {info: title=I18n

}
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
  • 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 ([
  • language
Table of Contents
outlinetrue

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

Translation bundles

There are 2 types of files for localized messages:

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:

...

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

...

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

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

 

How to use 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={})
{code}

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')
{code}

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 : 

GWT API

How to contribute

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

...

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.
It's recommended copy the English bundles 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.