Section: User Contributed Perl Documentation (3)
Updated: 2009-06-26


Locale::Maketext::Gettext - Joins the gettext and Maketext frameworks 


In your localization class:

  package MyPackage::L10N;  use base qw(Locale::Maketext::Gettext);  return 1;

In your application:

  use MyPackage::L10N;  $LH = MyPackage::L10N->get_handle or die "What language?";  $LH->bindtextdomain("mypackage", "/home/user/locale");  $LH->textdomain("mypackage");  $LH->maketext("Hello, world!!");

If you want to have more control to the detail:

  # Change the output encoding  $LH->encoding("UTF-8");  # Stick with the Maketext behavior on lookup failures  $LH->die_for_lookup_failures(1);  # Flush the MO file cache and re-read your updated MO files  $LH->reload_text;  # Set the encoding of your maketext keys, if not in English  $LH->key_encoding("Big5");  # Set the action when encode fails  $LH->encode_failure(Encode::FB_HTMLCREF);

Use Locale::Maketext::Gettext to read and parse the MO file:

  use Locale::Maketext::Gettext;  %Lexicon = read_mo($MOfile);


Locale::Maketext::Gettext joins the GNU gettext and Maketextframeworks. It is a subclass of Locale::Maketext(3)that follows the way GNU gettext works. It works seamlessly, bothin the sense of GNU gettext and Maketext. As a result, you enjoyboth their advantages, and get rid of both their problems, too.

You start as an usual GNU gettext localization project: Work onPO files with the help of translators, reviewers and Emacs. Turnthem into MO files with msgfmt. Copy them into the appropriatelocale directory, such as/usr/share/locale/de/LC_MESSAGES/

Then, build your Maketext localization class, with your base classchanged from Locale::Maketext(3) toLocale::Maketext::Gettext. That is all. 


$LH->bindtextdomain(DOMAIN, LOCALEDIR)
Register a text domain with a locale directory. Returns "LOCALEDIR"itself. If "LOCALEDIR" is omitted, the registered locale directoryof "DOMAIN" is returned. This method always success.
Set the current text domain. Returns the "DOMAIN" itself. If"DOMAIN" is omitted, the current text domain is returned. Thismethod always success.
$text = $LH->maketext($key, @param...)
Lookup the $key in the current lexicon and return a translatedmessage in the language of the user. This is the same method inLocale::Maketext(3), with a wrapper thatreturns the text message "encode"d according to the current"encoding". Refer to Locale::Maketext(3) forthe maketext plural notation.
$text = $LH->pmaketext($ctxt, $key, @param...)
Lookup the $key in a particular context in the current lexicon andreturn a translated message in the language of the user. Use``--keyword=pmaketext:1c,2'' for the xgettext utility.
Retrieve the language tag. This is the same method inLocale::Maketext(3). It is readonly.
Set or retrieve the output encoding. The default is the sameencoding as the gettext MO file. You can specify "undef", to returnthe result in unencoded UTF-8.
Specify the encoding used in your original text. The "maketext"method itself is not multibyte-safe to the _AUTO lexicon. If you areusing your native non-English language as your original text and youare having troubles like:

Unterminated bracket group, in:

Then, specify the "key_encoding" to the encoding of your originaltext. Returns the current setting.

WARNING: You should always use US-ASCII text keys. Usingnon-US-ASCII keys is always discouraged and is not guaranteed tobe working.

Set the action when encode fails. This happens when the output textis out of the scope of your output encoding. For exmaple, outputChinese into US-ASCII. Refer to Encode(3) for thepossible values of this "CHECK". The default is "FB_DEFAULT",which is a safe choice that never fails. But part of your text maybe lost, since that is what "FB_DEFAULT" does. Returns the currentsetting.
Maketext dies for lookup failures, but GNU gettext never fails.By default Lexicon::Maketext::Gettext follows the GNU gettextbehavior. But if you are Maketext-styled, or if you need a bettercontrol over the failures (like me :p), set this to 1. Returns thecurrent setting.

Note that lookup failure handler you registered with fail_with() onlywork when die_for_lookup_failures() is enabled. if you disabledie_for_lookup_failures(), maketext() never fails and lookup failurehandler will be ignored.

Purge the MO text cache. It purges the MO text cache from the baseclass Locale::Maketext::Gettext. The next time "maketext" iscalled, the MO file will be read and parse from the disk again. Thisis used when your MO file is updated, but you cannot shutdown andrestart the application. For example, when you are a co-hoster on amod_perl-enabled Apache, or when your mod_perl-enabled Apache is toovital to be restarted for every update of your MO file, or if youare running a vital daemon, such as an X display server.


%Lexicon = read_mo($MOfile);
Read and parse the MO file. Returns the read %Lexicon. The returnedlexicon is in its original encoding.

If you need the meta infomation of your MO file, parse the entry$Lexicon{""}. For example:

  /^Content-Type: text\/plain; charset=(.*)$/im;  $encoding = $1;

"read_mo()" is exported by default, but you need to "useLocale::Maketext::Gettext" in order to use it. It is not exportedfrom your localization class, but from the Locale::Maketext::Gettextpackage.



WARNING: do not try to put any lexicon in your language subclass.When the "textdomain" method is called, the current lexicon will bereplaced, but not appended. This is to accommodate the way"textdomain" works. Messages from the previous text domain shouldnot stay in the current text domain.

An essential benefit of this Locale::Maketext::Gettext over theoriginal Locale::Maketext(3) is that: GNU gettext is multibyte safe, but Perl source is not. GNU gettextis safe to Big5 characters like \xa5\x5c (Gong1). But if you followthe current Locale::Maketext(3) document andput your lexicon as a hash in the source of a localization subclass,you have to escape bytes like \x5c, \x40, \x5b, etc., in the middleof some natural multibyte characters. This breaks these charactersin halves. Your non-technical translators and reviewers will bepresented with unreadable mess, ``Luan4Ma3''. Sorry to say this, butit is weird for a localization framework to be not multibyte-safe.But, well, here comes Locale::Maketext::Gettext to rescue. WithLocale::Maketext::Gettext, you can sit back and relax now, leavingall this mess to the excellent GNU gettext framework.

The idea of Locale::Maketext::Getttext came fromLocale::Maketext::Lexicon(3), a greatwork by Autrijus. But it has several problems at that time (version0.16). I was first trying to write a wrapper to fix it, but finallyI dropped it and decided to make a solution towardsLocale::Maketext(3) itself.Locale::Maketext::Lexicon(3) should befine now if you obtain a version newer than 0.16.

Locale::Maketext::Gettext also solved the problem of lack of theability to handle the encoding inLocale::Maketext(3). I implement this sincethis is what GNU gettext does. When %Lexicon is read from MO filesby "read_mo()", the encoding tagged in gettext MO files is used to"decode" the text into the internal encoding of Perl. Then, whenextracted by "maketext", it is "encode"d by the current"encoding" value. The "encoding" can be set at run time, sothat you can run a daemon and output to different encodingaccording to the language settings of individual users, withouthaving to restart the application. This is an improvement to theLocale::Maketext(3), and is essential todaemons and "mod_perl" applications.

You should trust the encoding of your gettext MO file. GNU gettext"msgfmt" checks the illegal characters for you when you compile yourMO file from your PO file. The encoding form your MO files arealways good. If you try to output to a wrong encoding, part of yourtext may be lost, as "FB_DEFAULT" does. If you do not like this"FB_DEFAULT", change the failure behavior with the method"encode_failure".

If you need the behavior of auto Traditional Chinese/SimplfiedChinese conversion, as GNU gettext smartly does, do it yourself withEncode::HanExtra(3), too. There may be asolution for this in the future, but not now.

If you set "textdomain" to a domain that is not "bindtextdomain" tospecific a locale directory yet, it will try search system localedirectories. The current system locale directory search order is:/usr/share/locale, /usr/lib/locale, /usr/local/share/locale,/usr/local/lib/locale. Suggestions for this search order arewelcome.

NOTICE: MyPackage::L10N::en->maketext(...) is not availableanymore, as the "maketext" method is no more static. That is asure result, as %Lexicon is imported from foreign sourcesdynamically, but not statically hardcoded in Perl sources. But thedocumentation of Locale::Maketext(3) does notsay that you can use it as a static method anyway. Maybe you werepracticing this before. You had better check your existing code forthis. If you try to invoke it statically, it returns "undef".

"dgettext" and "dcgettext" in GNU gettext are not implemented.It is not possible to temporarily change the current text domain inthe current design of Locale::Maketext::Gettext. Besides, it ismeaningless. Locale::Maketext is object-oriented. You can alwaysraise a new language handle for another text domain. This isdifferent from the situation of GNU gettext. Also, the categoryis always "LC_MESSAGES". Of course it is. We are gettext andMaketext.

Avoid creating different language handles with differenttextdomain on the same localization subclass. This currentlyworks, but it violates the basic design of Locale::Maketext(3). InLocale::Maketext(3), %Lexicon is saved as aclass variable, in order for the lexicon inheritance system to work.So, multiple language handles to a same localization subclass sharesa same lexicon space. Their lexicon space clash. I tried to avoidthis problem by saving a copy of the current lexicon as an instancevariable, and replacing the class lexicon with the current instancelexicon whenever it is changed by another language handle instance.But this involves large scaled memory copy, which affects theproformance seriously. This is discouraged. You are adviced to usea single textdomain for a single localization class.

The "key_encoding" is a workaround, not a solution. There is nosolution to this problem yet. You should avoid using non-Englishlanguage as your original text. You will get yourself into troubleif you mix several original text encodings, for example, joiningseveral pieces of code from programmers all around the world, withtheir messages written in their own language and encodings. Solutionsuggestions are welcome.

"pgettext" in GNU gettext is implemented as "pmaketext", in orderto look up the text message translation in a particular context.Thanks to the suggestion from Chris Travers. 


GNU gettext never fails. I tries to achieve it as long as possible.The only reason that maketext may die unexpectedly now is``Unterminated bracket group''. I cannot get a better solution to itcurrently. Suggestions are welcome.

You are welcome to fix my English. I have done my best to thisdocumentation, but I am not a native English speaker after all. ^^; 


Locale::Maketext(3),Locale::Maketext::TPJ13(3),Locale::Maketext::Lexicon(3),Encode(3), bindtextdomain(3),textdomain(3). Also, please refer to the official GNUgettext manual at <>. 


imacat <> 


Copyright (c) 2003-2008 imacat. All rights reserved. This program is freesoftware; you can redistribute it and/or modify it under the same termsas Perl itself.




This document was created byman2html,using the manual pages.