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

Provided by: liblocale-maketext-gettext-perl_1.32-3_all

NAME

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

SYNOPSIS

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

DESCRIPTION

       Locale::Maketext::Gettext::Functions is a functional interface to Locale::Maketext::Gettext(3) (and
       Locale::Maketext(3)).  It works exactly the GNU gettext way.  It plays magic to Locale::Maketext(3) for
       you.  No more localization class/subclasses and language handles are required at all.

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

FUNCTIONS

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.

textdomain(DOMAIN)
Set the current text domain. Returns the "DOMAIN" itself. if "DOMAIN" is omitted, the current text
domain is returned. This method always success.

get_handle(@languages)
Set the language of the user. It searches for an available language in the provided @languages list.
If @languages was not provided, it looks checks environment variable LANG, and HTTP_ACCEPT_LANGUAGE
when running as CGI. Refer to Locale::Maketext(3) for the magic of the "get_handle".

$message = maketext($key, @param...)
Attempts to translate a text message into the native language of the user, by looking up the
translation in an MO lexicon file. Refer to Locale::Maketext(3) for the "maketext" plural grammar.

$message = __($key, @param...)
A synonym to "maketext()". This is a shortcut to "maketext()" so that 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 be caught with xgettext.

$message = dmaketext($domain, $key, @param...)
Temporarily switch to another text domain and attempts to translate a text message into the native
language of the user in that text domain. Use "--keyword=dmaketext:2" for the xgettext utility.

$message = pmaketext($context, $key, @param...)
Attempts to translate a text message in a particular context into the native language of the user.
Use "--keyword=pmaketext:1c,2" for the xgettext utility.

$message = dpmaketext($domain, $context, $key, @param...)
Temporarily switch to another text domain and attempts to translate a text message in a particular
context into the native language of the user in that text domain. Use "--keyword=dpmaketext:2c,3"
for the xgettext utility.

encoding(ENCODING)
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.

key_encoding(ENCODING)
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.

WARNING: You should always use US-ASCII text keys. Using non-US-ASCII keys is always discouraged and
is not guaranteed to be working.

encode_failure(CHECK)
Set the action when encode fails. This happens when the output text is out of the scope of your
output encoding. For example, 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.

die_for_lookup_failures(SHOULD_I_DIE)
Maketext dies for lookup failures, but GNU gettext never fails. By default
Lexicon::Maketext::Gettext follows the GNU gettext behavior. But if you are Maketext-styled, or if
you need a better control over the failures (like me :p), set this to 1. Returns the current
setting.

reload_text()
Purges the MO text cache. By default MO files are cached after they are read and parsed from the
disk, to reduce I/O and parsing overhead on busy sites. reload_text() purges this cache, so that
updated MO files can take effect at run-time. This is used when your MO file is updated, but you
cannot shutdown and restart the application. for example, when you are a virtual host on a
mod_perl-enabled Apache, or when your mod_perl-enabled Apache is too vital to be restarted for every
update of your MO file, or if you are running a vital daemon, such as an X display server.

%Lexicon = read_mo($MO_file)
Read and parse the MO file. Returns the read %Lexicon. The returned lexicon is in its original
encoding.

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

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

NOTES

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

       You  can  now  add/remove  languages/MO files at run-time.  This is a major improvement over the original
       Locale::Maketext::Gettext(3) (and Locale::Maketext(3)).  This is done by registering localization classes
       with random IDs, so that the same text domain can be re-declared infinitely,  whenever  needed  (language
       list   changes,   LOCALEDIR   changes,   etc.)    This   is  not  possible  to  the  object-interface  of
       Locale::Maketext::Gettext(3) (and Locale::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" to specific a locale directory yet, it
       will try search system locale  directories.   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.

STORY

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

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

       always  fails if $LH is not initialized yet.  For this reason, "maketext" can hardly be employed in error
       handlers to output graceful 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 every application, why should I not make a
       solution to the localization framework itself?  This is a common problem to every localization  projects.
       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  lower  down  its
       barrier,  be  friendly to the beginners, in order to encourage the use of localization and globalization.
       Apparently the current practice of Locale::Maketext(3) does not satisfy this request.

       The third reason is:  Since Locale::Maketext::Gettext(3) imports the lexicon from  foreign  sources,  the
       class  source  file  is  left empty.  It exists only to help the "get_handle" method looking for a proper
       language handle.  Then, why not make it disappear, and be generated  whenever  needed?   Why  bother  the
       programmers to put an empty class source file there?

       How neat can we be?

       imacat, 2003-04-29

BUGS

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

       "encoding", "key_encoding", "encode_failure" and "die_for_lookup_failures" are not mod_perl-safe.   These
       settings  affect the whole process, including the following scripts it is going to run.  This is the same
       as "setlocale" in POSIX(3).  Always set them at the very beginning of your  script  if  you  are  running
       under  mod_perl.   If  you  do not like it, use the object-oriented Locale::Maketext::Gettext(3) instead.
       Suggestions are welcome.

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

AUTHOR

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

COPYRIGHT

       Copyright  (c) 2003-2021 imacat. All rights reserved. This program is free software; you can redistribute
       it and/or modify it under the same terms as Perl itself.

perl v5.36.0                                       2022-10-15             Locale::Maketex...text::Functions(3pm)