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




In your localization class:

  package MyPackage::L10N;
  return 1;

In your application:

  use MyPackage::L10N;

If you want to have more control to the detail:

  # Change the output encoding
  # Stick with the Maketext behavior on lookup failures
  # Set the action when encode fails


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






$LH->bindtextdomain(DOMAIN, LOCALEDIR)
Register a text domain with a locale directory. Returns LOCALEDIR itself. If LOCALEDIR is omitted, the registered locale directory of 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. This method always success.

Lookup the $key in the current lexicon and return a translated message in the language of the user. This is the same method in Locale::Maketext(3), with a wrapper that returns the text message encoded according to the current encoding. Refer to Locale::Maketext(3) for the maketext plural notation.



Set or retrieve the output encoding. The default is the same encoding as the gettext MO file. You can specify undef, to return the 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 are using your native non-English language as your original text and you are having troubles like:

Unterminated bracket group, in:

Then, specify the key_encoding to the encoding of your original text. Returns the current setting.


Set the action when encode fails. This happens when the output text is out of the scope of your output encoding. For exmaple, output Chinese into US-ASCII. Refer to Encode(3) for the possible values of this CHECK. The default is FB_DEFAULT, which is a safe choice that never fails. But part of your text may be lost, since that is what FB_DEFAULT does. Returns the current setting.





%Lexicon = read_mo($MOfile);


  $encoding = $1;

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


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



Locale::Maketext::Gettext also solved the problem of lack of the ability to handle the encoding in Locale::Maketext(3). I implement this since this is what GNU gettext does. When %Lexicon is read from MO files by read_mo(), the encoding tagged in gettext MO files is used to decode the text into the internal encoding of Perl. Then, when extracted by maketext, it is encoded by the current encoding value. The encoding can be set at run time, so that you can run a daemon and output to different encoding according to the language settings of individual users, without having to restart the application. This is an improvement to the Locale::Maketext(3), and is essential to daemons 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 your MO file from your PO file. The encoding form your MO files are always good. If you try to output to a wrong encoding, part of your text may be lost, as FB_DEFAULT does. If you do not like this FB_DEFAULT, change the failure behavior with the method encode_failure.




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



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





Locale::Maketext(3), Locale::Maketext::TPJ13(3), Locale::Maketext::Lexicon(3), Encode(3), bindtextdomain(3), textdomain(3). Also, please refer to the official GNU gettext manual at http://www.gnu.org/software/gettext/manual/.


imacat <imacat@mail.imacat.idv.tw>


