AS3Gettext

Probably you’ve already taken a look at the new ActionScript3.
One of the greatest addition is the ByteArray, which provides methods and properties to optimize reading, writing, and working with binary data.That’s great! Thanks to this new class I finally managed to create an ActionScript porting of gettext. Ok, stop.. what’s gettext? I think some background info is necessary before continue…

1. What’s gettext?

Gettext is used by many software for providing a localization of their interface.

Usually, programs are written and documented in English, and use English at execution time for interacting with users. This is true not only from within GNU, but also in a great deal of proprietary and free software. Using a common language is quite handy for communication between developers, maintainers and users from all countries. On the other hand, most people are less comfortable with English than with their own native language, and would rather be using their mother tongue for day to day’s work, as far as possible. Many would simply love seeing their computer screen showing a lot less of English, and far more of their own language. GNU `gettext’ is an important step for the GNU Translation Project, as it is an asset on which we may build many other steps. [cut] (read more)

GNU gettext HTML manual is available here
Remember to download gettext first: ftp://ftp.gnu.org/gnu/gettext

2. How gettext works?

Basically gettext uses these steps:
2.1 Preparing Source
One of the great things of gettext is that it is capable of scan your sourcecode and create a table of the strings which should be translated. For this reason there is just one change you have to do to your sources:
Write your strings as they should appear in the default language (usually English), but enclosed in a global _() function call.
This mean that if you are writing this:
var button:Button = new Button();
button.label = "Click me";
if you’re going to manage your project using gettext you have to change the above code into:
var button:Button = new Button();
button.label = _("Click me");
That’s the only change you have to do in your code. An this is already comfortable, for code maitenance and readibility…
in my final example then I’ve created the function _(), which simply return the static method gettext.translate:
public function _(name:String):String
{
 return gettext.translate(name);
}
2.2 .PO and .MO files
gettext will create automatically a translation table, starting from an “app.fil” file, which is just a text file with a list of all the source file gettext should look into.
2.2.1 First time execution
The first time you need to create the first .po file, using this command line (be sure you’ve installed xgettext first from the GNU project wite):
xgettext -f app.fil -L Python --from-code=UTF-8 -d SEPY -no-wrap -s
this command means:
xgettext, get the list of source files from app.fil file,
then consider source files as Python files (actionscript is not available by default..)
and read them using UTF-8 codec. Use the domain name “SEPY” (output filename)
–no-wrap means what it should not break long lines
-s sort output
(this is exactly the same I used for creating SEPY localization files.)
A new file called SEPY.po is created. This is the base of all the translations. Copy this file into SEPY_it.po (for italian), SEPY_nl.po (for Dutch), SEPY_fr.po (for French).. and for all the languages your application need to be translated. Now give these files to your translator, or try to use babelfish to translate by your own 🙂
All the .po files are written in these way (they still are text files):
#: index.mxml:59
msgid "Add new folder"
msgstr ""

#: index.mxml:60
msgid "An Error occurred, or the package need to be recompiled first"
msgstr ""
It gives you information where the string appears in the file/line, the original string and the translated one (msgstr). You have to put your translations into the msgstr string
There’s also a very useful application called poedit, which an help you in translated string more easily.
2.2.2 .PO Management
You will certainly modify your code, strings etc.. thus probably also the translations need to be updated or added during time. Also in this important aspect GNU gettext help you a lot, because you dont need to remember which string you’ve changed, added or removed, and above all you dont need to write from scratch all the translations once you’ll create the new .po files!
All you have to do is update the .po files and merge the new content with the ole ones:
use the above command to recreate the original .po file:
xgettext -f app.fil -L Python --from-code=UTF-8 -d SEPY -no-wrap -s
then use:
msgmerge -s SEPY_it.po SEPY.po > SEPY_it.po.new
del SEPY_it.po
ren SEPY_it.po.new SEPY_it.po
Your old SEPY_it.po files has now been updated with the new content. You have only to open it and change the translations if needed.
2.2.3 Create the .MO files
.mo file is the final binary file loaded from your application for localize the GUI.

Important note: you dont need to translate all the strings. Maybe you can’t find a valid translation, or for certain string, such as “file” and “exit”, you want to leave the original string. Just leave the message untranslated, gettext will use the original string if it can’t find its translation

this is the code you have to write once your .po files are translated:
msgfmt --output-file=locale/it/LC_MESSAGES/SEPY.mo SEPY_it.po
That’s all. It may seems complicated the first time, don’t worry, but with a little batch file everything will be really really easy.

3. Why gettext?

Now probably you’re asking why you shoul use this way for localize your applications.. I can tell about my experience with desktop applications and flash… I never like the way flash suggest localizations through XML files. XML files are great for many things, but they are unmanageable for this kind of purpose. I also used XML files for manage localization in SEPY for many times, and every time i had to change/add or delete a translation string it was a pain! Once I switched to gettext i only code using english for every string, then a simple batch file update and merge all my .po files and once the other contributors send me the updated .po file I just need to compile it

4. Actionscript implementation

Here you can find the documentation api
And a little demonstration using Flex2 (requires flash player 9)
And the .mxml file is located here
As you can see in the source code all the strings have been inserted into the global function _(). That’s gettext!
Basically has this workflow: import first the gettext class using: then assign event listeners to it:
ln = new gettext();
ln.addEventListener("complete", this.handleEvent);
ln.addEventListener("ioError",  this.handleEvent);
ln.addEventListener("error",    this.handleError);
  • complete: everything goes fine and now you can start using the translations table
  • ioerror : probably the file you’re looking for isnt’ there..
  • error  : this error is generated by the .mo parser, maybe the file is corrupt or it is invalid
finally install it:
ln.translation("SEPY", "http://www.sephiroth.it/_temp/flex/gettext/locale/", "de");
ln.install();
ln.translation accept these arguments:
  • domain: that is the filename (SEPY.mo)
  • locale directory: specify where the locale dir is located, otherwise it will look into “locale/” by default
  • language: the language in iso format
According to the above explanation gettext will load locale/de/LC_MESSAGES/SEPY.mo file. Once the “complete” event is fired you can start using your localized translations.

5. Download