NAME

HTML::Template::Compiled::Plugin::I18N - Internationalization for HTC

$Id: I18N.pm 124 2009-08-04 20:15:08Z steffenw $

$HeadURL: https://htc-plugin-i18n.svn.sourceforge.net/svnroot/htc-plugin-i18n/trunk/lib/HTML/Template/Compiled/Plugin/I18N.pm $

VERSION

0.02

SYNOPSIS

create a translator class

package MyProjectTranslator;

sub translate {
    my ($class, $arg_ref) = @_;

    return $arg_ref->{text};
}

initialize plugin and then the template

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
    ) ],
    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();

DESCRIPTION

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.

TEMPLATE SYNTAX

text only

static text values

<%TEXT VALUE="some static text"%>
<%TEXT VALUE="some static text" ESCAPE=HTML%>

The 2nd parameter of the method translate (translator class) will set to:

{
    text => 'some staic text',
}

text from a variable
```
<%TEXT a.var%>
<%TEXT a.var ESCAPE=HTML%>
```
The 2nd parameter of the method translate (translator class) will set to:
```
{
    text => $a->var(), # or $a->{var}
}
```

formatter

1 formatter

<%TEXT VALUE="some **marked** text" FORMATTER="markdown"%>

The 2nd parameter of the method translate (translator class) will set to:

{
    text      => 'some **marked** text',
    formatter => [qw( markdown )],
}

more formatters

<%TEXT VALUE="some **marked** text" FORMATTER="markdown|second"%>

The 2nd parameter of the method translate (translator class) will set to:

{
    text      => 'some **marked** text',
    formatter => [qw( markdown second)],
}

Locale::Maketext placeholders

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 VALUE="Hello [_1]!" _1="world" _1_ESCAPE=0%>
<%TEXT VALUE="Hello [_1]!" _1="world" ESCAPE=HTML%>
<%TEXT VALUE="Hello [_1]!" _1="world" _1_ESCAPE=0 ESCAPE=HTML%>

The 2nd parameter of the method translate (translator class) will set to:

{
    text     => 'Hello [_1]!',
    maketext => [ qw( world ) ],
    # escapes processed already
}

with a variable

<%TEXT VALUE="Hello [_1]!" _1_VAR="var.with.the.value"%>
<%TEXT VALUE="Hello [_1]!" _1_VAR="var.with.the.value" _1_ESCAPE=0%>
<%TEXT VALUE="Hello [_1]!" _1_VAR="var.with.the.value" ESCAPE=HTML%>
<%TEXT VALUE="Hello [_1]!" _1_VAR="var.with.the.value" _1_ESCAPE=0 ESCAPE=HTML%>

The 2nd parameter of the method translate (translator class) will set to:

{
    text     => 'Hello [_1]!',
    maketext => [ $var->with()->the()->value() ], # or $var->{with}->{the}->{value}
    # escapes processed already
}

mixed samples

<%TEXT VALUE="The [_1] is [_2]." _1="window" _2="blue" %>
<%TEXT a.text                    _1="window" _2_VAR="var.color" %>

Locale::TextDomain placeholders

Allow gettext during initialization.

HTML::Template::Compiled::Plugin::I18N->init(
    allow_gettext => $true_value,
    ...
);

with a static value

<%TEXT VALUE="Hello {name}!" _name="world"%>
<%TEXT VALUE="Hello {name}!" _name="world" _name_ESCAPE=0%>
<%TEXT VALUE="Hello {name}!" _name="world" ESCAPE=HTML%>
<%TEXT VALUE="Hello {name}!" _name="world" _name_ESCAPE=0 ESCAPE=HTML%>

The 2nd parameter of the method translate (translator class) will set to:

{
    text    => 'Hello {name}!',
    gettext => { name => 'world' },
    # escapes processed already
}

with a variable

<%TEXT VALUE="Hello {name}!" _name_VAR="var.with.the.value"%>
<%TEXT VALUE="Hello {name}!" _name_VAR="var.with.the.value" _name_ESCAPE=0%>
<%TEXT VALUE="Hello {name}!" _name_VAR="var.with.the.value" ESCAPE=HTML%>
<%TEXT VALUE="Hello {name}!" _name_VAR="var.with.the.value" _name_ESCAPE=0 ESCAPE=HTML%>

The 2nd parameter of the method translate (translator class) will set to:

{
    text    => 'Hello {name}!',
    gettext => { name => $var->with()->the()->value() },
    # escapes processed already
}

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"

escaping rules

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

no extra escape set

The default escape will be used for the value and the placeholders.
```
<%TEXT VALUE="..."%>
<%TEXT VALUE="..." _1="..."%>
<%TEXT VALUE="..." _name="..."%>
```

escape set

A given escape ignores the default escape for the value and the placeholders.

<%TEXT VALUE="..." ESCAPE="..."%>
<%TEXT VALUE="..." _1="..."    ESCAPE="..."%>
<%TEXT VALUE="..." _name="..." ESCAPE="..."%>

placeholder escape set

A given placeholder escape ignores the default escape and the escape. At example the default escape is 'DDD'.

<%TEXT VALUE="..." _1="..." _1_ESCAPE="PPP" _2="..."%>
              ^^^      ^^^                      ^^^
escape DDD ____|        |                        |
escape PPP _____________|                        |
escape DDD ______________________________________|

<%TEXT VALUE="..." _name1="..." _name1_ESCAPE="PPP" _name2="..."%>
              ^^^          ^^^                              ^^^
escape DDD ____|            |                                |
escape PPP _________________|                                |
escape DDD __________________________________________________|

<%TEXT VALUE="..." _1="..." _1_ESCAPE="PPP" _2="..." ESCAPE="EEE"%>
              ^^^      ^^^                      ^^^
escape EEE ____|        |                        |
escape PPP _____________|                        |
escape EEE ______________________________________|

<%TEXT VALUE="..." _name1="..." _name1_ESCAPE="PPP" _name2="..." ESCAPE="EEE"%>
              ^^^          ^^^                              ^^^
escape EEE ____|            |                                |
escape PPP _________________|                                |
escape EEE __________________________________________________|

EXAMPLE

Inside of this Distribution is a directory named example. Run this *.pl files.

SUBROUTINES/METHODS

class method init

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,
    translator_class => 'TranslatorClassName',
    escape_plugins   => [ qw(
        the same like
        HTML::Template::Compiled->new(plugin => [qw( ...
        but escape plugins only
    )],
);

class method register

HTML::Template::Compiled will call this method to register this plugin.

HTML::Template::Compiled::Plugin::I18N->register();

sub escape

Called from compiled code only.

$escaped_string = HTML::Template::Compiled::Plugin::I18N::escape(
    $string,
    @escapes,
);

sub 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',
    ...
});

DIAGNOSTICS

missing escape plugin or translator class

Can not find package ...

text

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.

maketext

double maketext placeholder

Error in template filename, plugin package. Can not use maktext position n twice. _n="..."
double maketext placeholder escape

Error in template filename, plugin package. Can not use maktext escape position n twice. _n_ESCAPE="..."
escape plugin is not configured at method init

Error in template filename, plugin package. Maketext escape ... at _n_ESCAPE is unknown.

gettext

double gettext palaceholder

Error in template filename, plugin package. Can not use gettext key name twice. _name="..."
double gettext placeholder escape

Error in template filename, plugin package. Can not use gettext escape name twice. _name_ESCAPE="..."
escape plugin is not configured at method init

Error in template filename, plugin package. Gettext escape ... at _name_ESCAPE is unknown.
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="..."

or

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

or

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

CONFIGURATION AND ENVIRONMENT

Call init method before HTML::Template::Compiled->new(...).

DEPENDENCIES

Carp

English

Hash::Util

Data::Dumper

HTML::Template::Compiled

HTML::Template::Compiled::Token

HTML::Template::Compiled::I18N::DefaultTranslator

INCOMPATIBILITIES

not known

BUGS AND LIMITATIONS

not known

AUTHOR

Steffen Winkler

LICENSE AND COPYRIGHT

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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

create a translator class

initialize plugin and then the template

DESCRIPTION

TEMPLATE SYNTAX

text only

formatter

Locale::Maketext placeholders

Locale::TextDomain placeholders

escaping rules

EXAMPLE

SUBROUTINES/METHODS

class method init

class method register

sub escape

sub TEXT

DIAGNOSTICS

text

maketext

gettext

CONFIGURATION AND ENVIRONMENT

DEPENDENCIES

INCOMPATIBILITIES

BUGS AND LIMITATIONS

SEE ALSO

AUTHOR

LICENSE AND COPYRIGHT

Module Install Instructions