Translate LogicalDOC

As of August 2009 there are two alternative method for translating LogicalDOC,
The new Translation Program on LaunchPad and the traditional method based on Java properties.

New Translation Program

Starting from 03 August 2009 there is a new interface for translations of  LogicalDOC on Launchpad.
This new program has been chosen to help us in keeping aligned translations of LogicalDOC (scattered in various plugins) with the various releases of the program.
Above all we needed a system with a simple interface to do the translations in which even a person who is not expert in Java can make its contribution.
Rosetta at the same time (so called the translation software) allows us to visually check the progress of translation by monitoring the situation also on the various package, not only thanks to its suggestion interfaces Rosetta can speed-up the translation that can also be done in parallel by several people.
Moreover Launchpad - Rosetta provides a review system to verify the most sensitive translations.

Requirements

• You must read English well.
• You must write well in your native language.
• You need two hours (estimated) to translate about 500 English words. If someone has started translating this language, there will be less work. If you do not have time to translate all the strings, please first translate those in the appplication template (package). It is OK to translate some strings but not others.

Procedure

Follow this procedure:

1. Create a Launchpad account if you don't already have one. LogicalDOC (and many other projects) use Launchpad to manage translations. Your Launchpad account name will be given credit for the translation in the LogicalDOC release notes (unless you email me otherwise), so keep this in mind when picking the account name.
2. Visit the LogicalDOC translation page to type translations.
3. Click on your language.
4. Change All items to Untranslated items and click Change.
5. Type and save your translations.
6. Change Untranslated items to Items with new suggestions and click Change to browse items marked by others for review.
   

Getting the updated version of a translation

You can obtain the latest version of a translation directly from Logical Objects sending a request to the following address: translations@logicaldoc.it or you can wait for the regular localization bundle. The bundle of localization are issued with a frequency of about 2 weeks, 14 days.
Otherwise you can do everything from yourself.

The only important thing is that Launchpad Rosetta is a system based on Gettext and then works with files with extensions .pot (template) and .po (translation).
Therefore to work with this system you must first convert properties in .po (phase IN) and then convert back the files from .po to Java properties (phase OUT).

Follow the instructions:

1. From the LogicalDOC translations page, click Download, choose your language, choose selected files, choose PO format, and download.
2. Check your email for the link.
3. Download the file.
4. Rename the file to your your locale code (German is application-de.po, for example).
5. Launch the conversion program to convert from the Gettext format (.po files) to properties file (Java ResourceBundle)

po2prop -t application.properties application-de.po application_de.properties

sample command that convert application Po in German back to application_de.properties using the base property file application.properties as template

1. Move the converted .properties files to the 'class' folder of your LogicalDOC installation
   eg: c:\apache-tomcat-6.0.20\webapps\logicaldoc\WEB-INF\classes\i18n
2. Run LogicalDOC.

Working with translations in Gettext format

This section describes how to convert .properties files into .po files, how to translate them, how to update translation from an old version and how to turn the .po files back to .properties. The means of converting are provided by Translate Toolkit.

Detailed documentation can be found at http://translate.sourceforge.net/wiki/toolkit/prop2po . This section will concentrate on applying this in the LogicalDOC translation workflow.

About the Gettext framework

Gettext framework uses the .po file format. .po files contain both original (English) strings and corresponding strings in target language. That way, the meaning of once translated string will never change, except that it may not be used in a later version of the translated software.

Compare this to .properties files, which use name=value pairs, where the name identifies the string. The problem with this emerges when updating strings. There's no easy way to tell that the original name=value in the old version has a different value for the same name in the new version.

Po files contain header with information about the translator and format of the .po file. We won't need to use the header in our workflow in any way, so you can safely ignore complaints from your translation tool about headers containing default values.

Plain .po files without translations are called .pot files (templates). Format is the same as in .po files.

The benefit of Gettext is that it's widespread in the open source world (thus it's likely that translators are familiar with it) and there are quite a few tools supporting it.

Converting .properties to .po

First, we'll create an empty template (application.pot) from the base (English) .properties file (application.properties):

prop2po -P application.properties application.pot 

You can safely copy application.pot to application-ja.po (Japanese) and start translating it. Some tools recognize templates by the .pot extension but if you don't use such tool, you can create a .po file right away.

Translating .po files

Editing .po files is described in detail in the Gettext manual.

.po files are plain text files in a special format, so you may use any text editor to edit them. However if you do, there are two things to pay attention to. First, you will need to specify the encoding used in the header (e.g. "Content-Type: text/plain; charset=UTF-8\n"). Second, you ought to run a check once in a while to see if you didn't break the format:

msgfmt -c -v application-ja.po > /dev/null 

A simple, lightweight and multiplatform GUI editor for .po files is Poedit or Virtaal.

Reusing old translations

To create a translation of new version while reusing the unchanged strings from the old version, run:

prop2po --duplicates=msgctxt -t application_ja.properties application_ja-old.properties application-ja.po 

where application_ja.properties is the japanese .properties file (current version), application_ja-old.properties is the old translation in .properties format and it will create application-ja.po, which is the .po file for the new version with the old strings already translated! What remains to do is translate the new and changed ones. There will be even so called "fuzzy" strings - guesses how the string might be translated, which might save you some typing.

Tip: If you have your old translation in .po format, you can use msgmerge to make the old translation a base for your new version.

Converting .po back to .properties

The last step is to convert your translated .po file to a .properties file in your language.

po2prop -t application.properties application-ja.po application_ja.properties 

This takes application.properties, which is the original Master .properties file (current version) and application-ja.po, which is your translated .po file as input and produces application_ja.properties, which is the LogicalDOC translation for Japanese.

Note: The created .properties file is now in ASCII (Unicode characters are represented by escape sequences) just like LogicalDOC requires them. So there's no need to run native2ascii on them!

Once you're confident with this workflow, remember to look up more tips in the Translate Toolkit's prop2po page. Other useful tools include: pofilter - for finding translation errors, pogrep - searching translations and poterminology - for building a translation glossary.

Traditional Java properties

Procedure

1. Get the Master Files of the Current Version from LogicalDOC's SourceForge.net site:
   LogicalDOCLanguageMasterPack-xxx.zip
   
   
2. Translate ore or more of the following property files:
   application_en.properties (Main localization file)
   application-email_en.properties (email plugin (import from mailbox))
   FacesMessageBundle_en.properties (ICEfaces messages (validation form errors))
   

Verifying translations

1. Make a Copy of  the translated files into the appropriate folder of your logicaldoc web-application
   eg.: C:\tomcat-6.0.20\webapps\logicaldoc\WEB-INF\classes\i18n
   
2. Use the cmd line utility native2asci over the copy of the translated files, this is needed beacause java reads only ASCII characters from .properties, so native characters needs to be escaped. See my response on the Help forum of LogicalDOC translated character.
   
3. Turn Off and Restart the LogicalDOC web-application or Tomcat.
4. Login into LogicalDOC choosing ENGLISH as language
   

Share your work with the Community

Send your translation (specifying the language) to the following address: translations@logicaldoc.it or attach it to an issue in our Issue Tracking system: http://issues.logicaldoc.com

ASAP, our development team will create a plugin to support the language of which you have submitted the translations.
Why there is the need to create a plugin?

The LogicalDOC Development Team