Localization of Plugins

Most of the plugins involved with the site generation are fully internationalized. This means that adapting them to another language, a process known as localization, is very easy. All that is needed is to download a couple of properties files and start translating the texts in them. If you want to provide a patch for an unsupported language, there are detailed instructions below.

For the basic site generation there are currently files for three components that needs to be localized to support a new language: Maven Site Plugin, Maven Project Info Reports Plugin and Maven Doxia Tools.

Note: The links to SVN below goes to the latest development code. So the files may be newer than the ones included in the latest release.

In the table below you can see our localized plugins and which languages they are available in.

Plugin ca cs da de es fr gl hu it ja ko lt nl no pl pt pt_BR ru sk sv tr zh_CN zn_TW l10n report SVN
Changelog - - - OK - - - - - - - - - - - - - - - OK - - - l10n report SVN
Changes - - - OK - OK - - - - - - - - - - OK - - OK - - - l10n report SVN
Checkstyle - - - OK - OK - - - - - - - - - - OK - - OK - - - l10n report SVN
Dependency - - - OK - - - - - - - - - - - - OK - - OK - - - l10n report SVN
DOAP - - - OK OK OK - - - - - - - - - - - - - - - - - l10n report SVN
Doxia Integration Tools OK OK OK OK OK OK OK OK OK OK OK OK OK OK OK OK OK OK OK OK OK OK OK l10n report SVN
Javadoc - - - OK - OK - - - - - - OK - - - - - - OK - - - l10n report SVN
JXR - - - OK - OK - - - - - - - - - - - - - OK - - - l10n report SVN
PMD - - - OK - OK - - OK - - - OK - - - OK - - OK - - - l10n report SVN
Plugin - - - OK - OK - - - - - - - - - - - - - OK - - - l10n report SVN
Project Info Reports - OK - OK OK OK OK OK OK OK OK OK OK OK OK OK OK OK OK OK OK OK OK l10n report SVN
Surefire report - - - OK - - - - - - - - - - - - - - - OK - - - l10n report SVN
Site OK OK OK OK OK OK OK OK OK OK OK OK OK OK OK OK OK OK OK OK OK OK OK l10n report SVN

Is your favourite plugin missing a localization for your language? Please help us expand the language support by following the instructions below.

Localizing a Plugin

  • Check out the source code for the plugin you want to add a translation to.
  • Find the resource bundles that needs to be translated. They are often found in the src/main/resources folder.
  • Copy the basefile for the bundle, i.e. the one without a language extension. The copy should have the same name as the original file, except for the addition of a language extension. If, for example, you want to translate the Checkstyle Plugin into Spanish, you would copy src/main/resources/checkstyle-report.properties to src/main/resources/checkstyle-report_es.properties.
  • Edit the new file and translate all the properties. Do not change the formating of the file, i.e. keep the current indentation and line breaks. This makes it easy to use a graphical diff tool to find missing keys in the file.
  • Convert the new file so that all non-US-ASCII characters are transformed into Unicode escapes, see below for a tool that can help with this.
  • Run "mvn install" for the plugin.
  • Configure a project to use the latest SNAPSHOT version of the plugin you are working on. Also configure the project to produce a site in the language you are adding a translation for. For Spanish, as we used in the example above, it would look like this:
      <build>
        <plugins>
          <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-site-plugin</artifactId>
            <configuration>
              <locales>es</locales>
            </configuration>
          </plugin>
        </plugins>
      </build>
  • Run "mvn site" on that project to test it.
  • When you are happy with your translation, create an issue in JIRA for the plugin in question, with a description like this: "Add Spanish translation". Take note of the issue number.
  • Create a patch file that contains your new translation. Use the issue number when you name the file:
    svn diff > MYISSUE-123.patch
  • Attach your patch file to the issue in JIRA.

Tools

There is a command line tool called native2ascii that can be used to convert a text file to use Unicode-encoded characters instead of native-encoded characters. This is part of the Java SDK and you can read more about it here. You use it like this:

native2ascii checkstyle-report_es.properties checkstyle-report_es-encoded.properties

Tools to find out the charset of a file

Tools to write a file in a given charset

Any editor like Notepad++, Eclipse, IntelliJ IDEA, ...

Tools to convert a file from one encoding to another encoding

  • Unix iconv command
  • Notepad++

References

Please refer to the Java Internationalization home page for an introduction to the topic.

You can also refer to this Sun FAQ: How Can I Determine the Encoding of a File?