Gallery2:Localization - Gallery Codex
Personal tools

Gallery2:Localization

From Gallery Codex

Localizing Gallery 2

Overview

Gallery is internationalized. Instead of containing language specific text messages, it tracks text in a special way so that it can be extracted and translated into other languages. Users will see a version of the text that has been converted into their own language.

In order for the users to see a localized version of Gallery's text, somebody must first translate the text messages that Gallery is going to display. This process is called "localization".

Here we try to outline how you can create and maintain localization files for the content in G2. It's not a particularly difficult thing to do but it requires us to keep the various files up to date whenever the underlying content changes. Luckily we have tools that will aid in this process.

Requirements

In order to really do this effectively, you need to have a few tools installed on your machine. I've only tested this process on a FreeBSD box, but my guess is that you won't have too much difficulty on Linux, Solaris, or other Unix variants. You may have difficulties following along on Windows, but it should be possible. The following should be installed and in your PATH:

gettext 
http://www.gnu.org/software/gettext/
gmake (or make)
http://www.gnu.org/software/make/make.html
php binary 
http://php.net
perl 
http://perl.com

Note: if you're using FreeBSD then you want to use gmake instead of make since FreeBSD's default make is not GNU compatible.

You also need the current G2 files to create up-to-date translations. It is best to work from current SVN or a nightly snapshot. The developer version of the latest G2 release will also work, but some of the strings for translation may be out of date.

Creating a new localization

Look around the Gallery distribution and you'll find a bunch of directories called "po". ("po" is a gettext term that stands for "portable object"). Here's one way to find them:

find . -type d -name po			<-- you type this

./themes/matrix/po	          	<-- you see this
./lib/tools/po
./modules/core/po
./modules/comment/po
./modules/netpbm/po

** Ignore the "lib/tools/po" directory.

These directories contain translation source files. You're going to create new files with an appropriate language code, and then fill them with translated text. The first thing to do is to identify the correct codes from the following two tables:

Language codes
http://www.gnu.org/software/gettext/manual/html_mono/gettext.html#SEC221
(or http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt)
Country codes
http://www.gnu.org/software/gettext/manual/html_mono/gettext.html#SEC222
(or http://www.iso.ch/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html)

In most cases you will need just the language code, such as "de" for German. To provide country specific translations for a language used in multiple countries you can use a code in the format xx_XX, such as "pt_BR" for Portuguese/Brazil. If you are unsure which to use, include both language and country. If you find a translation for your language already exists then move on to Maintaining a localization.

Once you've chosen the code, you need to create a new .po file for your code. Let's assume that you chose "de". For each po directory, you need to do this:

make de.po

This will find all text that is marked for localization ({g->text} in tpl files, translate() or i18n() in php code) and create a po file that is ready to be translated.

A word about text editors.

I personally am a fan of XEmacs so I'll be talking about XEmacs in my examples below. If you have instructions for other editors, please contribute them. XEmacs has a major mode called "po-mode" which, if you have it installed, you'll automatically wind up in if you edit a .po file. I'm not going to go into it here, but try it out if you have it.

Now edit de.po. It should have the Gallery license at the top. You'll need to customize these values:

Last-Translator
Put your name and email here in the format: "FirstName LastName <email@address>"
Language-Team
Put in the language and the -translations mailing list, eg: "German <gallery-translations@lists.sourceforge.net>"
Content-Type
Set this to "Content-Type: text/plain; charset=UTF-8\n"
We want you to use the UTF-8 character set because it allows us to render multiple languages on the same page which is nice for sites in one language that have user comments, etc in other languages.

Here's an example of a complete header from modules/core/po/de.po. Note how the authors have maintained the list of all previous translators as a courtesy.

# Previous translators (as far as known, add yourself here, please):
# - Jens Tkotz <jens@peino.de>
# - Ernesto Baschny <ernst@baschny.de>
...
#
msgid ""
msgstr ""
"Project-Id-Version: Gallery: Core 1.0.32\n"
"POT-Creation-Date: 2003-02-11 03:09-0800\n"
"PO-Revision-Date: 2006-03-05 02:25+0000\n"
"Last-Translator: Frederik Kunz <frederik.kunz@web.de>\n"
"Language-Team: German <gallery-devel@lists.sourceforge.net>\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=2; plural=(n != 1);\n"

If your language doesn't have plural form like in Chinese or Turkish, you need to change the following line too:

"Plural-Forms: nplurals=2; plural=(n != 1);\n"
    -> Change to "Plural-Forms: nplurals=1; plural=0;\n".

In this case, you need to translate only msgstr[0] and comment out or remove msgstr[1].

Then, look at the lines just below the Gallery license:

#, fuzzy
msgid ""
msgstr ""

The fuzzy keyword tells you that the translation of the block is incomplete. But once that you update the administration entries, you can remove the "#, fuzzy" line to allow the translation to compile later on.

Next, you'll see a series of blocks like this:

#, c-format		(<-- you'll only see this on some lines)
msgid "a message in english, with %d or %s tags in it"
msgstr ""

You need to put the translation for the English message into the msgstr block, between the quotes, for example:

#, c-format
msgid "a message in english, with %d or %s tags in it"
msgstr "eine Anzeige auf englisch, mit %d oder %s etikettiert in ihr"

Some msgid values contain hints to assist in translation:

#. HINT: Button label for Bold
msgid "B"
msgstr "F"

Note that the hint should not be translated or included in the msgstr text. You can request the addition of hint text for particular strings with the Translations Tracker. Specify the module/theme and the msgid. Note that the strings.raw file lists the file(s) where each msgid is used.

You really, really, really should put your editor into UTF-8 mode before editing these messages so that your editor can use the right character set. If you can't edit in UTF-8 for some reason, consider using the GNU "recode" program to convert your translation to UTF-8 before submitting it to us (or just send it anyway and we'll recode it).

If you're using XEmacs with MULE (its MULtilanguagE support) you can add the following to your ~/.xemacs/init.el

; Enable Unicode support (via Mule-UCS)
;
(require 'un-define)
(set-coding-priority-list '(utf-8))
(set-coding-category-system 'utf-8 'utf-8)

Then when you edit a file that is in UTF-8, it'll have a little "u" in left side of the status bar at the bottom of the screen. Try it out with an existing .po file to see what it looks like.

After doing a few translations, try it out to see how it looks. Run:

make install PO=de

And it will compile your .po file into a .mo file and install it in the appropriate place for the module.

As of Gallery 2.3, the correct place for .po and .mo files is eg the modules/mymodule/po directory. Previous versions of Gallery renamed the .mo file and moved it to eg modules/mymodule/locale/de/LC_MESSAGES/modules_mymodule.mo.

If you're updating the translations for an existing module and the locale/ directory already exists within the module directory structure then the updated .mo files are still copied there (pre 2.3 behaviour); if the locale directory doesn't exist then the files are created in the po/ directory. There is a formal API update notification for the correct location of .po and .mo files here: http://codex.galleryproject.org/Gallery2:API_Changes_Since_The_Last_Release#7.19_.3D.3E_7.20

Although the intention is that Gallery 2.3 will still install language files from the pre-2.3 (modules/mymodule/locale/...) there have been issues reported which are still under investigation.

Repeat this for every directory where you modified a .po file.

Finally, you need to edit modules/core/classes/GalleryTranslator.class and in function getLanguageData, add lines like this:

/* German */
$this->_supportedLanguages['de']['DE']['description'] = 'Deutsch';
$defaultCountry['de'] = 'DE';

The comment should be the name of the language in English; the language 'description' is the name of the language in that language.

Now, log onto G2 and in the User preferences (you may need to edit the user via the Site Administrator) you should see German appear in the dropdown, and if you select it and log on as that user you'll see your translated messages. Alternatively, add the Language selector block to your site using Theme settings.

Note: If the language change doesn't take effect, please review the precedence of the language settings (Session language > user preferences > site wide default language). In doubt, use the language block or toggle the language in your user preferences back and forth.

Submitting your localization

Now that you've got your localization created, you need to package it up and send it to us so that we can commit it into the repository. The best way to package it is like this:

cd gallery2
zip de.zip `find . -name de.po`

or:

cd gallery2
tar czf nl.tar.gz `find . -name nl.po`

This will make up a zipfile or tarball of just your translated files. Obviously, use your language code instead of de or nl above. Then, go to the Translations Tracker on the Gallery project page on SourceForge and click the "Submit New" button. Put your translation in the "Gallery 2" group and don't forget to attach the files (you must check the checkbox for attachment too!). If your translation doesn't get committed within a few days, jump on IRC (see help section) and talk to us about it.

Maintaining a localization

cd po
make de.po	(using German as an example)

This will extract all messages from the module that you're in and update the .po file. Look through the .po file for any blocks that have an empty msgstr, or are marked "fuzzy" and update them. After they are fixed, remove the fuzzy tag. You may find tags that look like this:

#, fuzzy
#~ msgid "User"
#~ msgstr "Gebruikersnaam"

The "#, fuzzy" means that its fuzzy, but the "#~" means that the string no longer exists in G2 (we probably deleted or changed it significantly). You can delete these entries.

You should do a quick check that gettext provides to validate your .po file:

msgfmt -v -c --stat de.po

When you've got everything right, run:

make install PO=de

The translation files get cached by PHP (which is why it's so fast) so you may not see change until you restart your web server. That's annoying, but I haven't figured a good workaround for it yet.

See the Creating a new localization section for testing info, and submit the new files to us. Also be aware of the change in the correct location of .mo and .po files with Gallery 2.3 detailed there. You may wish to migrate the language files to the new location as part of the maintenance, although that will mean the translations no-longer operate with pre G2.3 releases.

Where to go for help!

If you need help, there are three places to go:

The Gallery translations forums
http://galleryproject.org/forum/74
The gallery-translations mailing list
http://codex.galleryproject.org/index.php/Mailing_Lists
The Gallery IRC channel
#gallery on irc://chat.freenode.net

List of Translations

All available Gallery 2 translations, listed alphabetically along with the maintainers / translators. Some translations are 100% up to date and complete, others are only 2% complete or out of date. See: Localization Report. If you have the developer package of G2, you can run http://www.example.com/gallery/lib/tools/reports/localization.php to see the status of all installed translations.