Unix/Linux Go Back    


CentOS 7.0 - man page for locale::maketext::gettext (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(3)   User Contributed Perl Documentation   Locale::Maketext::Gettext(3)

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

SYNOPSIS
       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);

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

       You start as an usual GNU gettext localization project:	Work on PO files with the help of
       translators, reviewers and Emacs.  Turn them into MO files with msgfmt.	Copy them into
       the appropriate locale directory, such as /usr/share/locale/de/LC_MESSAGES/myapp.mo.

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

METHODS
       $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.

       $LH->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.

       $text = $LH->maketext($key, @param...)
	   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 "encode"d according to the current "encoding".  Refer to
	   Locale::Maketext(3) for the maketext plural notation.

       $text = $LH->pmaketext($ctxt, $key, @param...)
	   Lookup the $key in a particular context in the current lexicon and return a translated
	   message in the language of the user.   Use "--keyword=pmaketext:1c,2" for the xgettext
	   utility.

       $LH->language_tag
	   Retrieve the language tag.  This is the same method in Locale::Maketext(3).	It is
	   readonly.

       $LH->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.

       $LH->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.

       $LH->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.

       $LH->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.

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

       $LH->reload_text
	   Purge the MO text cache.  It purges the MO text cache from the base class
	   Locale::Maketext::Gettext.  The next time "maketext" is called, the MO file will be
	   read and parse from the disk again.	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.

FUNCTIONS
       %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;

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

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

       An essential benefit of this Locale::Maketext::Gettext over the original
       Locale::Maketext(3) is that: GNU gettext is multibyte safe, but Perl source is not.  GNU
       gettext is safe to Big5 characters like \xa5\x5c (Gong1).  But if you follow the current
       Locale::Maketext(3) document and put your lexicon as a hash in the source of a
       localization subclass, you have to escape bytes like \x5c, \x40, \x5b, etc., in the middle
       of some natural multibyte characters.  This breaks these characters in halves.  Your non-
       technical translators and reviewers will be presented with unreadable mess, "Luan4Ma3".
       Sorry to say this, but it is weird for a localization framework to be not multibyte-safe.
       But, well, here comes Locale::Maketext::Gettext to rescue.  With
       Locale::Maketext::Gettext, you can sit back and relax now, leaving all this mess to the
       excellent GNU gettext framework.

       The idea of Locale::Maketext::Getttext came from Locale::Maketext::Lexicon(3), a great
       work by Autrijus.  But it has several problems at that time (version 0.16).  I was first
       trying to write a wrapper to fix it, but finally I dropped it and decided to make a
       solution towards Locale::Maketext(3) itself.  Locale::Maketext::Lexicon(3) should be fine
       now if you obtain a version newer than 0.16.

       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 "encode"d 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".

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

       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 for this search order are welcome.

       NOTICE: MyPackage::L10N::en->maketext(...) is not available anymore, as the "maketext"
       method is no more static.  That is a sure result, as %Lexicon is imported from foreign
       sources dynamically, but not statically hardcoded in Perl sources.  But the documentation
       of Locale::Maketext(3) does not say that you can use it as a static method anyway.  Maybe
       you were practicing this before.  You had better check your existing code for this.  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 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.

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

       The "key_encoding" is a workaround, not a solution.  There is no solution to this problem
       yet.  You should avoid using non-English language as your original text.  You will get
       yourself into trouble if you mix several original text encodings, for example, joining
       several pieces of code from programmers all around the world, with their messages written
       in their own language and encodings.  Solution suggestions are welcome.

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

BUGS
       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 it currently.  Suggestions are welcome.

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

SEE ALSO
       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/>.

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(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 12:29 AM.