[wp-docs] Localization with gettext

[Ryan Boren]

We just committed the gettext l10n/i18n framework to CVS.

http://www.gnu.org/software/gettext/gettext.html

gettext is a mature, widely used localization framework.  It is pretty
much the defacto standard in the open source/free software realm.  KDE
and GNOME are two notable projects which use gettext.  They use it to
handle a huge number of translatable strings in dozens of languages.

http://i18n.kde.org/
http://www.gnome.org/i18n/

These projects provide some good info on working with the gettext
system.  The documents below contain a lot of information that won't
apply to us, but they are a good place to get the general idea.

http://i18n.kde.org/translation-howto/
http://developer.gnome.org/projects/gtp/l10n-guide/

Basically, in Wordpress, strings in the php files are marked for
translation using two "tags" which are actually functions.  They are:

__()
_e()

These accept a string as an argument.  For example:

__("Translate Me")
_e("Translate Me")

The only functional difference between the two methods is that _e()
echoes the string and __() simply returns the string.  __() is used when
you want to supply a string to a function.  _e() is used when you want
to output the string as part of your XHTML.

We have a tool which goes through all of the php files, extracting
strings that are marked by __() and _e().  A POT (Portable Object
Template) file is generated from the strings.  I have posted the current
POT file for 1.2 to the Wiki.  Please note that this is still changing,
rapidly.

http://wiki.wordpress.org/index.php/1.2%20WordpressPOT

Translators will take this file and copy it to a .po file named after
the ISO-639 language code for their language.  If the language has
different spellings and dialect in different countries, the ISO-3166
country code will also be used in the file name.  Here are some
examples:

ar.po     -- Arabic
en_GB.po  -- British English
en_CA.po  -- Canadian English
fr.po     -- French

A more complete list can be found here:

http://developer.gnome.org/projects/gtp/status/gnome-2.6/index.html

Once the translator has created a .po file from the .pot file, it is
time to start translating strings.  Looking at the file makes it evident
what needs to be done.  Each msgid contains an American English string
present in the php source files.  Below each msgid is a msgstr. 
Translations for a given msgid go in msgstr.  Pretty simple.

As strings are added, the translator can send the po file to the devs. 
>From the .po file the devs will create a .mo file.  MO (Machine Object)
is a compact, binary form of the PO file.  It is considerably smaller
and faster load.

The MO is the end of the line.  The MO provides full support for a given
language.  If a user places fr.mo in wp-includes/languages, BOOM, French
is supported.

We still need to add code to expose language selection in the admin UI. 
For now, there is a variable at the top of wp-includes/wp-l10n.php
called $locale which can be set to the desired ISO langauge and country
code.  If a corresponding .mo is found, it will be loaded and used to
perform string translation.

Now, here's where we ask for help.  We need the doc team to locate all
user visible strings that need to be translated and make sure they are
properly spelled, grammatically correct American English.  If you're
handy at reading the php source, you can also help us find and mark
strings for translation.  If you don't want to look at the source,
looking at the output of the default template and the various pages of
the admin interface and noting misspellings and bad grammar will be very
helpful.

Further, we need to update the WordPressLocalization Wiki page and start
organizing translation teams.  Anyone want to tackle the Wiki?  Most of
the information on it at the moment is now obsolete.

http://wiki.wordpress.org/index.php/WordPressLocalization

So, we have work to do.  If you have any questions, let me know.

Ryan