Latest revision as of 14:41, 29 March 2013

Creating a new translation

Geeklog has already been translated into more than 30 languages. If your language is not among them, you may want to check for a related language first. But usually, the best way to start a new translation is to make a copy of english.php (or english_utf-8.php) and give it the English(!) name of your language.

Things to consider:

• The character set: If you're using UTF-8, that should be reflected in the name of the language file (i.e. the filename should end in ..._utf-8.php).
• Dialects / variations of a language: Local variations of a "main" language should also be reflected in the file name. See, for example, portuguese_brazil.php for "Portuguese, as spoken in Brazil".

Language file

Geeklog includes several language files for different purposes. There is a main language file, used by Geeklog's core code. The plugins that are bundled with Geeklog (and all 3rd party plugins) use their own language files. Another language file is used by the install script:

language/english.php
plugins/calendar/language/english.php
plugins/links/language/english.php
plugins/polls/language/english.php
plugins/spamx/language/english.php
plugins/staticpages/language/english.php
plugins/xmlsitemap/language/english.php
public_html/admin/install/language/english.php

You don't need to translate all the language files at once. The plugins will fall back to using the English language file automatically when they can't find a file for the current language.

So it's best to start with the main language file (in the toplevel language directory) and work your way from there.

Character set and text direction

Your language file should define the character set to use for your language:

$LANG_CHARSET = 'iso-8859-1';

For languages that are written right-to-left (e.g. Hebrew, Arabic), you should also set

$LANG_DIRECTION = 'rtl';

If $LANG_DIRECTION is not set in the language file, left-to-right is assumed.

Note: These two options should only be set in the main language file and the language file for the install script. Plugins will automatically use the character set and text direction as defined in the main language file.

The $LANG arrays

Geeklog uses PHP arrays to define the texts used, e.g.

$LANG01 = array(
    1 => 'Contributed by:',
    2 => 'read more',
(...)
);

Whenever Geeklog needs the text for "read more", it refers to $LANG01[2] and picks up the localized text from the current language file. So you only need to translate the text to the right of the => sign.

Note that some language arrays are using a textual key instead of a number, e.g.

$LANG_ACCESS = array(
    'access' => 'Access',

Again, you should only translate the text on the right side. PHP also allows text strings as an array index, so the word "Access" would be referred to by $LANG_ACCESS['access'] (and if you changed the 'access' on the left side, this wouldn't work any more).

Updating a translation

Not all language files are still actively supported. Therefore, you may notice that some texts will show up in English even when you switched to a different language. The language files, as shipped with Geeklog, are updated such that they include all the required texts. Where a translation is not available, the English text is used.

To update a translation, you can either browse through the language file and look for English texts, or you can translate texts as required as you run into them when using your Geeklog site.

Translating the Geeklog Documentation

As of Geeklog 1.6.0, the documentation that ships with Geeklog has been moved from docs to docs/english. So now it's possible to translate the Geeklog documentation, too.

Note: The directory name for the translated documentation should not include a character set name (i.e. it should be "italian", even if you're using UTF-8 for the translated files). This is because the documentation is independent from Geeklog and its character set, so there's no need to have UTF-8 and non-UTF-8 versions.

Getting help

The geeklog-translations mailing list is probably the best place to go to when you need help with your translation. We recommend that all maintainers of language files subscribe to this list, as we will also post information about changes in the language files in upcoming Geeklog releases on this list.

Publishing your translation

The best way to publish your translation is to get it included in the official Geeklog tarballs. Pre-announcements of upcoming releases will be posted on the geeklog-translations mailing list, so that you can finish your work in time to be included.

Between Geeklog releases, you can always upload your translation on geeklog.net. Make sure to compress your language file(s) as .zip or .tar.gz files to prevent special characters from being corrupted.

Translations uploaded to geeklog.net will also usually be picked up to be included in future Geeklog releases.

Sending Patches

If you are familiar with Mercurial, you can also send patches for the language files (instead of sending the complete files). Using Mercurial's export format has the advantage that your name would show up in the list of changes in our Mercurial repository.

Sending the complete file is usually easier, though. Choose whatever is easier for you.