Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Template::Plugin::GettUser3Contributed Perl DocumeTemplate::Plugin::Gettext(3)

NAME
       Template::Plugin::Gettext - Gettext Support For the Template Toolkit
       Version 2

SYNOPSIS
       Load the	plug-in	in templates:

	   [% USE Gettext('com.textdomain.my', 'fr', 'utf-8', 'DIRECTORIES'...)	%]
	   [% Gettext.gettext('Hello, world!') %]

	   [% 'Hello, world!' |	gettext	%]

       Or alias	"Gettext":

	   [% USE gtx =	Gettext('com.textdomain.my', 'fr', 'utf-8', 'DIRECTORIES'...) %]
	   [% gtx.gettext('Hello, world!') %]

       Use method invocations:

	   [% Gettext.gettext("Hello, world!") %]
	   [% Gettext.xgettext("Hello, {name}!", name => 'John Doe') %]

       Or filters (without the prefix):

	   [% FILTER gettext %]
	   Hello, world!
	   [% END %]

	   [% 'Hello, world!' |	gettext	%]

	   [% FILTER xgettext(name => 'John Doe') %]
	   Hello, {name}!
	   [% END %]

       You have	a multitude of methods available:

	   [% gtx.gettext("Hello, user!") %]
	   [% gtx.xgettext("Hello, {user}!", user => 'John Doe') %]
	   [% gtx.ngettext("One	document deleted.",
			   "Multiple documents deleted."),
			   42) %]
	   [% gtx.nxgettext("One document deleted.",
			    "{num} documents deleted."),
			    42,
			    num	=> 42) %]
	   [% gtx.npgettext("context..."
			    "One document deleted.",
			    "Multiple documents	deleted."),
			    42)	%]
	   [% gtx.npxgettext("context...",
			     "One document deleted.",
			     "{num} documents deleted."),
			     42,
			     num => 42)	%]

DESCRIPTION
       The Template::Plugin::Gettext plug-in makes the GNU gettext API
       <https://www.gnu.org/software/gettext/> available for documents using
       the Template Toolkit version 2 <http://template-toolkit.org/>.  See
       <https://github.com/gflohr/Template-Plugin-Gettext> for an overall
       picture and the recommended tool-chain.

FUNCTIONS
       The following methods produce translatable content:

       [% gtx.gettext(STRING) %]
	   Retrieves the translation for STRING.

       [% gtx.xgettext(STRING, PLACEHOLDER1 => VALUE1, PLACEHOLDER2 => VALUE2,
       ...) %]
	   Gets	the translation	for a string with placeholders and
	   interpolates	values into it.	 Placeholders have the format
	   <{PLACEHOLDER}>.  For a literal left	curly brace you	can use	this
	   hack:

	       [% gtx.xgettext("String with {LBRACE}PLACEHOLDERS{RBRACE}",
			       LBRACE => "{", RBRACE =>	"}") %]

       [% gtx.pgettext(CONTEXT,	STRING)	%]
	   Retrieves the translation for STRING	in context CONTEXT.  You
	   should use message context to disambiguate identical	strings	that
	   require different translations depending on the context.  See this
	   example for an explanation:

	       [% gtx.gettext("State: ") %]
		   [% gtx.gettext("Open")] | [%	gtx.gettext("Close") %]

	       [% gtx.gettext("Menu:") %]
		   [% gtx.pgettext("menu", "Open")]
		   [% gtx.gettext("Save")]
		   [% gtx.gettext("Save	As")]
		   [% gtx.pgettext("menu", "Close")]

	   The strings "Open" and "Close" in line 2 are	adjectives. As
	    menu entries they are verb forms and will have a different
	    translation	in many	languages.

	    In doubt: Only use contexts	if one of your translators complains
	    about a message having multiple meanings.

       [% gtx.pxgettext(CONTEXT, STRING, PLACEHOLDER1 => VALUE1, PLACEHOLDER2
       => VALUE2) %]
	   Get the translation for STRING with placeholders in context
	   CONTEXT.  This is a mixture of "xgettext()" and "pgettext()"	above.

       [% gtx.nxgettext(SINGULAR, PLURAL, COUNT, PLACEHOLDER1 => VALUE1,
       PLACEHOLDER2 => VALUE2) %]
	   Retrieves the translation for the string with the singular form
	   SINGULAR and	the plural from	PLURAL,	both possibly containing
	   placeholders.  The correct form is picked based upon	the third
	   argument COUNT.

	   Example:

	       [% gtx.nxgettext("One document deleted",
				"{num} documents deleted"),
				count,
				num => count) %]

	   In English this will	produce	"42 documents deleted" if the variable
	   count has the value 42.  It will produce "One document deleted" if
	   the variable	count has the value 1.

	   In other languages, the rules for plural forms may be a lot simpler
	   (for	example	Chinese, which has no plural) or a lot more
	   complicated (for example Russian with two or	Slovenian with even 3
	   plural forms).  Using ngettext() gives your translators the chance
	   to provide syntactically correct translations for these cases.

       [% gtx.npxgettext(CONTEXT, SINGULAR, PLURAL, COUNT, PLACEHOLDER1	=>
       VALUE1, PLACEHOLDER2 => VALUE2) %]
	   Putting it all together:  For message context CONTEXT the
	   translation for a message in	SINGULAR and PLURAL is retrieved based
	   on the argument COUNT.  Possible placeholders are expanded.

	   The function	is a mixture of	xgettext(), ngettext(),	and
	   pgettext(), see above!

       [% gtx.ngettext(SINGULAR, PLURAL, COUNT)	%]
	   Useless function, provided for completeness.	 Use nxgettext()
	   instead, so that you	can interpolate	the value of COUNT!

       [% gtx.npgettext(CONTEXT, SINGULAR, PLURAL, COUNT) %]
	   Useless function, provided for completeness.	 Use npxgettext()
	   instead, so that you	can interpolate	the value of COUNT!

       In fact,	you have also all the keywords used for	"FILTERS" available
       but those not listed here have such an odd ordering of arguments	that
       they are	not listed here.

   FILTERS
       The entire gettext API is also exposed as a filter.  There are two
       things to note here:

       o   When	used as	filters, you don't prefix the method names.  It' s
	   "gettext" not "Gettext.gettext" or "gtx.gettext()".

       o   The filters with message contexts have rather strange names,	for
	   example:

	       [% FILTER gettextp("greeting") %]
	       Hello, world!
	       [% END %]

	       or 100 %	equivalent:

	       [% 'Hello, world!' | gettextp("greeting") %]

	   Why?	The text between FILTER	and END	resp. the text in front	of the
	   pipe	symbol | is always the first argument.	This plug-in therefore
	   tries to make the first argument the	most significant one.  Nobody
	   stops you from writing the following:

	       [% FILTER pgettext("Hello, world!") %]
	       greeting
	       [% END %]

	       or again	100 % equivalent:

	       [% 'greeting' | pgettext("Hello,	world!") %]

	   It produces exactly the same	results	as above but it	looks a	little
	   bit odd, doesn't it?

	   It would have been arguably better understandable to	silently
	   reorder the arguments, when using the plug-in as a filter.  But it
	   would break extraction of your strings with xgettext-tt2
	   (Locale::XGettext::TT2) because the string extractor	would then
	   confuse the arguments.

	   But stay relaxed! Message contexts are rarely needed, and when you
	   need	them, you have to live with this little	weirdness.

	   In order to avoid confusion,	those filters that would not have the
	   translatable	string (in the singular	form) where one	would expect
	   it, are not documented here.

       You can use the following filters:

       [% STRING | gettext %]
       [% FILTER gettext %]STRING[% FILTER %]
	   Retrieves the translation for STRING.

       [% STRING | xgettext(PLACEHOLDER1 => VALUE1, PLACEHOLDER2 => VALUE2,
       ...) %]
       [% FILTER xgettext(PLACEHOLDER1 => VALUE1, PLACEHOLDER2 => VALUE2, ...)
       %]STRING[% END %]
	   Gets	the translation	for a string with placeholders and
	   interpolates	values into it.	 Placeholders have the format
	   <{PLACEHOLDER}>.  For a literal left	curly brace you	can use	this
	   hack:

	       [% "String with {LBRACE}PLACEHOLDERS{RBRACE}" | xgettext(LBRACE => "{", RBRACE => "}") %]

       [% STRING | gettextp(CONTEXT) %]
       [% FILTER gettextp(CONTEXT) %]STRING[% END %]
	   Retrieves the translation for STRING	in context CONTEXT.  You
	   should use message context to disambiguate identical	strings	that
	   require different translations depending on the context. See	the
	   docuemntation for pgettext()	in "FUNCTIONS" above for more details!

       [% STRING | xgettextp(CONTEXT, STRING, PLACEHOLDER1 => VALUE1,
       PLACEHOLDER2 => VALUE2) %]
       [% FILTER xgettextp(CONTEXT, STRING, PLACEHOLDER1 => VALUE1,
       PLACEHOLDER2 => VALUE2) %]STRING[% END %]
	   Get the translation for STRING with placeholders in context
	   CONTEXT.  This is a mixture of "xgettext()" and "pgettext()"	above.

       [% SINGULAR | nxgettext(PLURAL, COUNT, PLACEHOLDER1 => VALUE1,
       PLACEHOLDER2 => VALUE2) %]
       [% FILTER nxgettext(PLURAL, COUNT, PLACEHOLDER1 => VALUE1, PLACEHOLDER2
       => VALUE2) %]SINGULAR[% END %]
	   Retrieves the translation for the string with the singular form
	   SINGULAR and	the plural from	PLURAL,	both possibly containing
	   placeholders.  The correct form is picked based upon	the third
	   argument COUNT.

	   Example:

	       [% "One document	deleted" | nxgettext("{num} documents deleted"),
						     count,
						     num => count) %]

	   In English this will	produce	"42 documents deleted" if the variable
	   count has the value 42.  It will produce "One document deleted" if
	   the variable	count has the value 1.

	   In other languages, the rules for plural forms may be a lot simpler
	   (for	example	Chinese, which has no plural) or a lot more
	   complicated (for example Russian with two or	Slovenian with even 3
	   plural forms).  Using ngettext() gives your translators the chance
	   to provide syntactically correct translations for these cases.

       [% SINGULAR | nxgettextp(PLURAL,	COUNT, CONTEXT,	PLACEHOLDER1 =>
       VALUE1, PLACEHOLDER2 => VALUE2) %]
       [% FILTER nxgettextp(PLURAL, COUNT, CONTEXT, PLACEHOLDER1 => VALUE1,
       PLACEHOLDER2 => VALUE2) %]SINGULAR[% END	%]
	   Putting it all together:  For message context CONTEXT the
	   translation for a message in	SINGULAR and PLURAL is retrieved based
	   on the argument COUNT.  Possible placeholders are expanded.

	   The filter is a mixture of xgettext(), ngettext(), and pgettext(),
	   see above!

       [% SINGULAR | ngettext(PLURAL, COUNT) %]
       [% FILTER ngettext(PLURAL, COUNT) %]SINGULAR[% END %]
	   Useless filter, provided for	completeness.  Use nxgettext()
	   instead, so that you	can interpolate	the value of COUNT!

       [% SINGULAR | ngettextp[(PLURAL,	COUNT, CONTEXT)	%]
       [% FILTER | ngettextp[(PLURAL, COUNT, CONTEXT) %]SINGULAR[% END %]
	   Useless filter, provided for	completeness.  Use nxgettextp()
	   instead, so that you	can interpolate	the value of COUNT!

       [% debug_locale %]
	   The plug-in implicitely calls web_set_locale() (see Locale::Util)
	   if a	language was specified in the USE statement.  The function
	   debug_locale() gives	you the	return value of	the call for debugging
	   purposes.  Example:

	       [% USE gtx = Gettext('com.mydomain.www',	de') %]

	       Using locale [% debug_locale() %].

	   This	way, you can determine whether setting the specified locale
	   actually worked.

CLASS METHODS
       textdomains
	   Returns a hash where	the keys are the textdomains found in
	   templates that invoked the plug-in, and the values are the
	   corresponding template file names.

	   The purpose of this method is to allow harvesting files that	should
	   be processed	by xgettext-tt2.

	   If the template is either "input text" or "input file handle", the
	   template variable "gettext_filename"	- if existing -	is assumed as
	   the template	name.  Rationale: "input text" and "input file handle"
	   are used by the Template Toolkit as aliases,	when reading from a
	   scalar or a file handle.

       resetTextdomains
	   Resets the hash described above for textdomain() to its initial,
	   empty state.

COPYRIGHT
       Copyright (C) 2016-2018 Guido Flohr (http://www.guido-flohr.net/).
       License LGPLv3+:	GNU General Public License version 3 or	later
       <http://gnu.org/licenses/lgpl.html>.  This is free software: you	are
       free to change and redistribute it.  There is NO	WARRANTY, to the
       extent permitted	by law.	 Copyright (C) 2016-2018 Guido Flohr
       <guido.flohr@cantanea.com>, all rights reserved.

SEE ALSO
       Template, Template::Manual::Filters, xgettext-tt2, perl

perl v5.32.1			  2018-11-04	  Template::Plugin::Gettext(3)

NAME | SYNOPSIS | DESCRIPTION | FUNCTIONS | CLASS METHODS | COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Template::Plugin::Gettext&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help