cattaDoc: New language translation

cattaDoc is prepared for translation into other languages, and it is relatively easy to do, although it will probably take some time to complete. English is the source language for cattaDoc which means that the translation is done from English. You can also look at other language translations for inspiration, provided you understand the other language :-)

A little bit of background information: Gettext is the technology behind Native Language Support (NLS) in cattaDoc. It takes care of all the static text strings in the PHP forms, ie. the user interface elements like headings, labels and explaining text.

However, there are also dynamic language elements in cattaDoc, like states and events and document types. These are all defined in the database and are as such not covered by gettext. These dynamic language elements are translated through PHP include files, all residing in the /inc sub-folder and having a file name in the form of incSwitchXyz.php.

The translation into a new language is a four-step exercise:

1. Create a new gettext source language file
2. Compile the gettext source file into a gettext binary language file
3. Add the new language translation to the PHP include files
4. Define the new language translation in cattaDoc

When a new version of cattaDoc is available, you will have to repeat steps no. 1-3, although in a slightly different way. Maintaining a language translation is much faster than a first time translation, since you can reuse your previous translation.

 

Create a new gettext source language file

The gettext source language file is an ASCII text file. An updated template containing all strings in cattaDoc is available in all versions in the cattadoc/po sub-folder: po/cattadoc.po.

Find the language code for the language you are going to translate into. A list of language codes can be found at lcweb.loc.gov/standards/iso639-2/langhome.html. If there is a 2 letter code for the language, use this.

Create a directory cattadoc/locale/language_code/LC_MESSAGES/, e.g. cattadoc/locale/de/LC_MESSAGES/ for a German translation. Copy cattadoc/po/cattadoc.po into this directory. This is the file that is going to be translated.

To translate the actual strings, fill in the msgstr after each msgid with the appropiate translation. There are a few tools - at least for Linux - which can make this job a bit easier at i18n.kde.org/translation-howto/gui-specialized-apps.html. However, I always use a good text editor.

 

Compile a new gettext binary language file

When you have completed the language translation in the gettext source file, you shall compile this source file into a gettext binary language file - with an .mo extension. For this you need the gettext program files - or binaries.

In my experience, gettext is available in most of the Linux distributions. You can download a Windows version of gettext from sourceforge.net/projects/gettext.

Convert the translated cattadoc.po into a binary file by running the command "msgfmt -o cattadoc.mo cattadoc.po" in the directory where the translated cattadoc.po is residing.

As an alternative, send the gettext source language file to me, and I will be happy to compile it for you. Well, always send the result to me, so that I can include it in the next release of cattaDoc!

 

Translate PHP include files

The sub-folder cattadoc/inc contains 9 PHP include files, also needing translation:

• incSwitchCat.php: Language translation for Company categories
• incSwitchDocType.php: Language translation for Document types
• incSwitchDTab.php: Language translation for Document classes
• incSwitchDtText.php: Language translation for base data: Document class text
• incSwitchEState.php: Language translation for Status names
• incSwitchEventName.php: Language translation for Event names
• incSwitchPTab.php: Language translation for Project classes
• incSwitchResDocType.php: Language translation for Resource document types
• incSwitchYesNo.php: Language translation for Yes/No display

In all the files, do the following:

1. Copy the whole section from "if" to "else" to a new if-section
2. Change the second "if" to "elseif" and replace the language value from, say, 'da_DK' into 'de'
3. Translate all the case sentences by replacing all the word(s) in the subsequent print sentence
4. Save the PHP include file

After finishing, send all the translated PHP include files to me, please!

 

Define number format

Number formats differ from one country to another. In the English speaking world, the thousand separator is a comma, whereas in Danish it is a dot. The only place cattaDoc displays numbers needing a thousand separator is for the file size in the document version display - defined in the file relDocVers.php.

Please put the appropriate code into this file - or inform me about the preferred thousand separator for your language.

 

Define new language in cattaDoc

Finally, you need to make cattaDoc aware of the new language so that users can select it as their preferred language. You need to be a system administrator in cattaDoc to do this.

1. In cattaDoc, enter system administration by clicking System in the search screen
2. Select "List & Create Languages" in the System administration menu
3. Enter the new language code
4. Enter the language display name - I recommend the English language name (e.g. German) followed by the native language name (e.g. Deutch)
5. Click the Save button - and you are done!

 

Maintaining translations

The text strings in cattaDoc will change over time. This means that strings that are already translated are no longer used and new strings are added. Therefore it is necessary to maintain the translations.

In principle, you have to do all the steps 1-3 all over again. Fortunately, there is a shorter way of doing the time-consuming step 1.

There will always be an updated template containing all strings in cattaDoc in cattadoc/po/cattadoc.po. To merge all new strings in this file into an existing translation, do the following:

1. Rename the previous gettext source language file - with a .po extension - in cattadoc/locale/language_code/LC_MESSAGES/ from cattadoc.po to old.po and copy it to the folder cattadoc/po (alongside the updated template in the same folder)
   
   
2. From the cattadoc/po folder, run the command "msgmerge old.po cattadoc.po --output-file=new.po"
   
   
3. Translate the missing entries in the file new.po
   • check for '#, fuzzy' entries - delete after changes
   • check for "" entries and fill out
   
   
   
4. Compile the edited new.po file into a binary cattadoc.mo file by running the command "msgfmt -o cattadoc.mo new.po"
   
   
5. Copy cattadoc.mo and new.po (as cattadoc.po) to the language directory, cattadoc/locale/language_code/LC_MESSAGES/

It might be necessary to restart Apache in order to reread the new language file.

 

Thanks to SquirrelMail for parts of this language translation guide.