Unix/Linux Go Back    


CentOS 7.0 - man page for locale::maketext::gettext::functions (centos section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


Locale::Maketext::Gettext::FuncUsersContributed Perl DocumLocale::Maketext::Gettext::Functions(3)

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 grammer.

       $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 catched 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($ctxt, $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, $ctxt, $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 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.

       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 co-hoster 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($MOfile)
	   Read and parse the MO file.	Returns the read %Lexicon.  The returned lexicon 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;

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.

SEE ALSO
       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 <http://www.gnu.org/software/gettext/manual/>.

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

COPYRIGHT
       Copyright (c) 2003-2008 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.16.3				    2014-06-09	  Locale::Maketext::Gettext::Functions(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 03:21 AM.