6. Localization howto

6.1. GForge localization system and status
6.2. Adding a new language
6.3. Format of the *.tab files
6.4. Updating a translation
6.5. Text content customization

6.1. GForge localization system and status

This short HOWTO explains how you can customize your local installation of GForge.

First, a quick course on the internationalisation system present in GForge.

The texts you can read on the web pages are not hard-coded. Instead, they are displayed as results of a function of several parameters. One of these parameters is the language in which you wish to display a piece of information, and another is some handle to identify the information you want to display. In GForge, this handle is made up of the “page name” and the “category” strings.

Knowing all the needed info, the function displays the appropriate text. How appropriate is this text? Well, that depends. First, a basic set of texts is loaded. Historically, this set is loaded in English. This set of texts makes the Base class, storing texts for all known “handles”.

This set of texts can then be partially or completely overloaded, e.g. for other languages: the handles present in the language overwrite the Base handles, and the ones not found keep their values from the Base class.

The language files are located in the www/include/languages directory.

The following languages are available in GForge :

  • The English language, being the original one in which GForge was written, is obviously complete.

  • The french translation is complete.

  • The Spanish (Castillan) translation is complete.

  • The Korean translation used to be complete.

  • The Dutch, Italian, Portuguese Brazilian and Swedish translations are pretty well advanced but not regularly updated.

  • The German, Japanese and Simplified Chinese translations are 20-50% complete.

  • The Catalan translation is a work in progress.

You might consider translating GForge into your language. If you do so, please also consider submitting your translated file to us so that future releases of GForge include your translated file by default.

6.2. Adding a new language

These are the steps to add a new language:

  1. Add a row in the supported_languages table in the gforge database:

    INSERT INTO supported_languages
    	(name, filename, classname, language_code)
    	VALUES ('German (Austria)',
    		'Austrian.class',
    		'Austrian',
    		'at'
    	);
    

    Note

    The language_code should follow the international language codings described in RFC 1766. For example, Portuguese Brazilian code is pt-br and not pt_BR.

  2. Copy the file Base.tab to Austrian.tab and place it in the www/languages/include folder.

  3. Translate the document

    Warning

    If you are not going to translate the entire document, please just override strings you translate.

  4. Submit the translation to the GForge project

6.3. Format of the *.tab files

The *.tab files are in a fairly straightforward format. Lines starting with a '#' character are ignored, other lines must be in the following format:

<pagename> TAB <category> TAB <data>

Warning

Please be careful to use TAB and not SPACE.

The <data> field can use variables in the form $1, $2, etc. These variables are defined by the script and there's no simple way of knowing what they are apart from looking at the script itself. To find out exactly what these variables are filled out with, search for the getText('<pagename>','<category'>) string in the scripts contained in the www/ and common/. This is not always easy to do.

Your best bet is to guess the meaning of the $1, $2, etc. variables from the non-customized text (either Base.tab or Foobaric.tab if it is defined).

Warning

*.tab files must be UTF-8 encoded.

6.4. Updating a translation

GForge is constantly developed and so translation files are regularly outdated. Thus translations should be regularly updated to be uptodate.

If you are maintaining a translation file, you may find useful language_file_merger.php script you can find in tools module (see GForge CVS repository for more information).

You can use the following command to merge your outdated language file with Base.tab :

php -q language_file_merger.php <your/gforge/install/root> <language> \
1>merge.tab 2>merge.log

You have to check lines with #TO_TRANSLATE# and #TO_REMOVE# flags and respectively translate them and remove them. Lines are already sorted by alphabetical order so you just have to add header information found in the previous YourLanguage.tab file to merge.tab file and replace YourLanguage.tab by merge.tab.

6.5. Text content customization

The text content can be somewhat customized. The GForge internationalisation system already provides a way to have different texts depending on user choice.

You might want to change page footers, or contact pages, or host names, or whatever you need to integrate your GForge your target audience (company, organisation, or even your own personal GForge).

The way you should usually go when you have to customize some text is the following:

  1. Find the bit of text you want to customize in Foobaric.tab;

  2. Copy and paste the appropriate line (including the “handle” -- the first two fields) in /etc/gforge/languages-local/Foobaric.tab or for theme specific customization in /etc/gforge/languages-local/<theme>/Foobaric.tab;

  3. Read it to find out about the $n variables;

  4. Replace the third field with my own customized version.

  5. If you use the localization caching system, remove cache files.