HTML::Template::Compiled::Plugin::I18N - Internationalization for HTC
$Id: I18N.pm 180 2010-10-29 19:44:26Z steffenw $
$HeadURL: https://htc-plugin-i18n.svn.sourceforge.net/svnroot/htc-plugin-i18n/trunk/lib/HTML/Template/Compiled/Plugin/I18N.pm $
1.04
use HTML::Template::Compiled; use HTML::Template::Compiled::Plugin::I18N; HTML::Template::Compiled::Plugin::I18N->init( # All parameters are optional. escape_plugins => [ qw( HTML::Template::Compiled::Plugins::ExampleEscape ) ], # At first write this not. Use the default translator. translator_class => 'MyProjectTranslator', ); my $htc = HTML::Template::Compiled->new( plugin => [ qw( HTML::Template::Compiled::Plugin::I18N HTML::Template::Compiled::Plugin::ExampleEscape ) ], scalarref => \'<%TEXT VALUE="Hello World!" %>', ); print $htc->output();
This translator class replaces the default translator.
package MyProjectTranslator; use HTML::Template::Compiled::Plugin::I18N; sub translate { my ($class, $arg_ref) = @_; # Translate the 'text'. # If maketext is allowed, replace the 'maketext' placeholders. # Alternative, if gettext is allowed, translate 'text' and 'plural' # and replace the 'gettext' palceholders. my $translation = your_translator( $arg_ref->{text}, ... ); # Escape the translated string now. if ( exists $arg_ref->{escape} ) { $translation = HTML::Template::Compiled::Plugin::I18N->escape( $translation, $params->{escape}, ); } # If formatters are allowed, run the formatters like Markdown. if ( exists $arg_ref->{formatter} ) { my $formatter_ref = $arg_ref->{formatter}; for my $formatter ( @{$formatter_ref} ) { # Call here a formatter like Markdown if (lc $formatter eq lc 'Markdown') { # $translation = ... $tanslation; } } } # If unescaped is allowed, replace at least the unescaped placholders. if ( exists $arg_ref->{unescaped} ) { $translation = HTML::Template::Compiled::Plugin::I18N->expand_unescaped( $translation, $arg_ref->{unescaped}, ); } return $translation; }
The Plugin allows you to create multilingual templates including maketext and/or gettext features.
Before you have written your own translator class, HTML::Template::Compiled::I18N::DefaultTranslator runs.
Later you have to write a translator class to join the plugin to your selected translation module.
An escape can be a "0" to ignore all inherited escapes. It can be a single word like "HTML" or a list concatinated by "|" like "HTML|BR".
Without escape
<%TEXT ... %> (if no default escape is set) <%TEXT ... ESCAPE=0%>
The 2nd parameter of the method translate (translator class) will set to:
{ ... }
Escape HTML as example
<%TEXT ... %> (default escape is set) <%TEXT ... ESCAPE=HTML%>
{ escape => 'HTML', ... }
More than one escape
<%TEXT ... ESCAPE=HTML|BR%>
{ escape => 'HTML|BR', ... }
Static text values
<%TEXT VALUE="some static text"%>
{ text => 'some staic text', ... }
Text from a variable
<%TEXT a.var%> <%TEXT NAME="a.var"%>
{ text => $a->var(), # or $a->{var} ... }
Allow maketext during initialization.
HTML::Template::Compiled::Plugin::I18N->init( allow_maketext => $true_value, ... );
With a static value
<%TEXT VALUE="Hello [_1]!" _1="world"%>
{ text => 'Hello [_1]!', maketext => [ qw( world ) ], }
With a variable
<%TEXT VALUE="Hello [_1]!" _1_VAR="var.with.the.value"%>
{ text => 'Hello [_1]!', maketext => [ $var->with()->the()->value() ], # or $var->{with}->{the}->{value} }
Mixed samples
<%TEXT VALUE="The [_1] is [_2]." _1="window" _2="blue" %> <%TEXT a.text _1="window" _2_VAR="var.color" %>
Allow gettext during initialization.
HTML::Template::Compiled::Plugin::I18N->init( allow_gettext => $true_value, ... );
<%TEXT VALUE="Hello {name}!" _name="world"%>
{ text => 'Hello {name}!', gettext => { name => 'world' }, }
<%TEXT VALUE="Hello {name}!" _name_VAR="var.with.the.value"%>
{ text => 'Hello {name}!', gettext => { name => $var->with()->the()->value() }, }
Plural forms with PLURAL, PLURAL_VAR, COUNT COUNT_VAR
<%TEXT VALUE="book" PLURAL="books" COUNT="1"%> <%TEXT VALUE="book" PLURAL="books" COUNT_VAR="var.num"%> <%TEXT VALUE="{num} book" PLURAL="{num} books" COUNT="2" _num="2"%>
For the last one, the 2nd parameter of the method translate (translator class) will set to:
{ text => '{num} book', plural => '{num} books', count => 2, gettext => { num => 2 }, }
Allow formatter during initialization.
HTML::Template::Compiled::Plugin::I18N->init( allow_formatter => $true_value, ... );
One formatter
<%TEXT VALUE="some **marked** text" FORMATTER="markdown"%>
{ text => 'some **marked** text', formatter => [qw( markdown )], }
More formatters
<%TEXT VALUE="some **marked** text" FORMATTER="markdown|second"%>
{ text => 'some **marked** text', formatter => [qw( markdown second)], }
Unescaped placeholders are written in the text like gettext placeholders. They are usable allone or in combination with maketext or gettext placeholders.
Allow unescaped placeholders during initialization.
HTML::Template::Compiled::Plugin::I18N->init( allow_unescaped => $true_value, ... );
<%TEXT VALUE="Hello" UNESCAPED_link_begin='<a href="...">' UNESCAPED_link_end='</a>'%>
{ text => 'Hello', unescaped => { link_begin => '<a href="...">', link_end => '</a>', }, }
<%TEXT VALUE="Hello" UNESCAPED_link_begin_VAR="var1" UNESCAPED_link_end_VAR="var2"%>
{ text => 'Hello {name}!', gettext => { var1 => $var1, var2 => $var2, }, }
Inside of this Distribution is a directory named example. Run this *.pl files.
Call init before the HTML::Template::Compiled->new(...) will called.
# all parameters are optional HTML::Template::Compiled::Plugin::I18N->init( throw => sub { croak @_; # this is the default } allow_maketext => $boolean, allow_gettext => $boolean, allow_formatter => $boolean, allow_unescaped => $boolean, translator_class => 'TranslatorClassName', escape_plugins => [ qw( the same like HTML::Template::Compiled->new(plugin => [qw( ... but escape plugins only )], );
HTML::Template::Compiled will call this method to register this plugin.
HTML::Template::Compiled::Plugin::I18N->register();
$escaped_string = HTML::Template::Compiled::Plugin::I18N->escape( $translated_string, $escapes_joined_by_comma, );
$finished_string = HTML::Template::Compiled::Plugin::I18N->expand_unescaped( $translated_and_escaped_string, $hash_ref_with_placeholders, );
Subroutine _parse_attributes
Subroutine _check_escape {
Subroutine _prepare_htc_code {
Subroutine TEXT
Do not call this method. It is used to create the HTC Template Code. This method is used as callback which is registerd to HTML::Template::Compiled by our register method.
It calls the translate method of the Translator class 'TranslatorClassNames'.
The translate method will called like
$translated = TranslatorClass->new()->translate({ text => 'result of variable lookup or VALUE', ... });
Missing escape plugin or translator class
Can not find package ...
Select NAME or VALUE
Error in template filename, plugin package. Do not use NAME and VALUE at the same time. NAME="..." VALUE="..."
Escape plugin is not configured at method init
Error in template filename, plugin package. Escape ... at ESCAPE is unknown.
Double maketext placeholder
Error in template filename, plugin package. Can not use maktext position n twice. _n="..."
Ddouble gettext palaceholder
Error in template filename, plugin package. Can not use gettext key name twice. _name="..."
Double gettext plural
Error in template filename, plugin package. Can not use PLURAL/PLURAL_VAR twice. PLURAL="..."
or
Error in template filename, plugin package. Can not use PLURAL/PLURAL_VAR twice. PLURAL_VAR="..."
Double gettext count
Error in template filename, plugin package. Can not use COUNT/COUNT_VAR twice. COUNT="..."
Error in template filename, plugin package. Can not use COUNT/COUNT_VAR twice. COUNT_VAR="..."
Double gettext context
Error in template filename, plugin package. Can not use CONTEXT/CONTEXT_VAR twice. CONTEXT="..."
Error in template filename, plugin package. Can not use CONTEXT/CONTEXT_VAR twice. CONTEXT_VAR="..."
Double formatter
Error in template filename, plugin package. Can not use FORMATTER twice. FORMATTER="..."
Call init method before HTML::Template::Compiled->new(...).
Carp
English
Hash::Util
Data::Dumper
HTML::Template::Compiled
HTML::Template::Compiled::Token
HTML::Template::Compiled::I18N::DefaultTranslator
not known
Hyper::Template::Plugin::Text This was the idea for this module. This can not support escape. This can not handle gettext. The module is too Hyper-ish and not for common use.
Steffen Winkler
Copyright (c) 2009 - 2010, Steffen Winkler <steffenw at cpan.org>. All rights reserved.
<steffenw at cpan.org>
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install HTML::Template::Compiled::Plugin::I18N, copy and paste the appropriate command in to your terminal.
cpanm
cpanm HTML::Template::Compiled::Plugin::I18N
CPAN shell
perl -MCPAN -e shell install HTML::Template::Compiled::Plugin::I18N
For more information on module installation, please visit the detailed CPAN module installation guide.