Section: User Contributed Perl Documentation (3)
Updated: 2008-02-19


Locale::Maketext::Gettext::Functions - Functional interface to Locale::Maketext::Gettext 


  use Locale::Maketext::Gettext::Functions;  bindtextdomain(DOMAIN, LOCALEDIR);  textdomain(DOMAIN);  get_handle("de");  print __("Hello, world!\n");


Locale::Maketext::Gettext::Functions is a functionalinterface toLocale::Maketext::Gettext(3) (andLocale::Maketext(3)). It works exactly the GNUgettext way. It plays magic toLocale::Maketext(3) for you. No morelocalization class/subclasses and language handles are required atall.

The "maketext", "dmaketext", "pmaketext" and "dpmaketext"functions attempt to translate a text message into the nativelanguage of the user, by looking up the translation in an MO lexiconfile. 


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.
Set the language of the user. It searches for an available languagein the provided @languages list. If @languages was not provided, itlooks checks environment variable LANG, and HTTP_ACCEPT_LANGUAGEwhen running as CGI. Refer toLocale::Maketext(3) for the magic of the"get_handle".
$message = maketext($key, @param...)
Attempts to translate a text message into the native language of theuser, by looking up the translation in an MO lexicon file. Refer toLocale::Maketext(3) for the "maketext" pluralgrammer.
$message = __($key, @param...)
A synonym to "maketext()". This is a shortcut to "maketext()" sothat it is cleaner when you employ maketext to your existing project.
($key, @param...) = N_($key, @param...)
Returns the original text untouched. This is to enable the text becatched with xgettext.
$message = dmaketext($domain, $key, @param...)
Temporarily switch to another text domain and attempts to translatea text message into the native language of the user in that textdomain. Use ``--keyword=dmaketext:2'' for the xgettext utility.
$message = pmaketext($ctxt, $key, @param...)
Attempts to translate a text message in a particular context into thenative language of the user. Use ``--keyword=pmaketext:1c,2'' forthe xgettext utility.
$message = dpmaketext($domain, $ctxt, $key, @param...)
Temporarily switch to another text domain and attempts to translatea text message in a particular context into the native language ofthe user in that text domain. Use ``--keyword=dpmaketext:2c,3'' forthe xgettext utility.
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.
Purges the MO text cache. By default MO files are cached after theyare read and parsed from the disk, to reduce I/O and parsing overheadon busy sites. reload_text() purges this cache, so that updated MOfiles can take effect at run-time. This is used when your MO file isupdated, but you cannot shutdown and restart the application. forexample, when you are a co-hoster on a mod_perl-enabled Apache, orwhen your mod_perl-enabled Apache is too vital to be restarted forevery update of your MO file, or if you are 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;


NOTE: Since localization classes are generated at run-time, it isnot possible to override the Maketext language functions, like"quant" or "numerate". If that is your concern, useLocale::Maketext::Gettext(3) instead.Suggestions are welcome.

You can now add/remove languages/MO files at run-time. This is amajor improvement over the originalLocale::Maketext::Gettext(3) (andLocale::Maketext(3)). This is done byregistering localization classes with random IDs, so that the sametext domain can be re-declared infinitely, whenever needed (languagelist changes, LOCALEDIR changes, etc.) This is not possible to theobject-interface ofLocale::Maketext::Gettext(3) (andLocale::Maketext(3)).

Language addition/removal takes effect only after "bindtextdomain"or "textdomain" is called. It has no effect on "maketext" calls.This keeps a basic sanity in the lifetime of a running script.

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 are welcome. 


The idea is that: I finally realized that, no matter how hard I try,I can never get a never-failure "maketext". A common wrapperlike:

  sub __ { return $LH->maketext(@_) };

always fails if $LH is not initialized yet. For this reason, "maketext" can hardly be employed in error handlers to outputgraceful error messages in the natural language of the user. So,I have to write something like this:

  sub __ {      $LH = MyPkg::L10N->get_handle if !defined $LH;      return $LH->maketext(@_);  }

But what if "get_handle" itself fails? So, this becomes:

  sub __ {      $LH = MyPkg::L10N->get_handle if !defined $LH;      $LH = _AUTO->get_handle if !defined $LH;      return $LH->maketext(@_);  }  package _AUTO;  use base qw(Locale::Maketext);  package _AUTO::i_default;  use base qw(Locale::Maketext);  %Lexicon = ( "_AUTO" => 1 );

Ya, this works. But, if I always have to do this in my everyapplication, why should I not make a solution to the localizationframework itself? This is a common problem to every localizationprojects. It should be solved at the localization framework level,but not at the application level.

Another reason is that: Programmers should be able to use"maketext" without the knowledge of object-oriented programming.A localization framework should be neat and simple. It should lowerdown its barrier, be friendly to the beginners, in order toencourage the use of localization and globalization. Apparentlythe current practice of Locale::Maketext(3)does not satisfy this request.

The third reason is: Since Locale::Maketext::Gettext(3) importsthe lexicon from foreign sources, the class source file is leftempty. It exists only to help the "get_handle" method looking fora proper language handle. Then, why not make it disappear, and begenerated whenever needed? Why bother the programmers to putan empty class source file there?

How neat can we be?

imacat, 2003-04-29 


Since maketext localization classes are generated at run time,Maketext language function override, like "quant" or "numerate", isnot available here. Suggestions are welcome.

"encoding", "key_encoding", "encode_failure" and"die_for_lookup_failures" are not mod_perl-safe. These settingsaffect the whole process, including the following scripts it isgoing to run. This is the same as "setlocale" inPOSIX(3). Always set them at the very beginning of yourscript if you are running under mod_perl. If you do not like it,use the object-orientedLocale::Maketext::Gettext(3) instead.Suggestions are welcome.

Smart translation between Traditional Chinese/Simplified Chinese,like what GNU gettext does, is not available yet. Suggestions arewelcome. 


Locale::Maketext(3),Locale::Maketext::TPJ13(3),Locale::Maketext::Gettext(3),bindtextdomain(3), textdomain(3).Also, please refer to the official GNU gettext 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.