NAME

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

$Id: I18N.pm 111 2009-07-21 06:40:42Z steffenw $

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

VERSION

0.01

SYNOPSIS

create a translator class

package MyProjectTranslator;

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

    return $params->{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 connect 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 were handled 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() ],
    # escapes were handled 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 were handled 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 were handled 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"

EXAMPLE

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

SUBROUTINES/METHODS

init

Call init before the HTML::Template::Compiled object will created.

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

register

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

register($class);

escape

Called from compiled code only.

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

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

$translator = TranslatorClass->new()->translate({
    text => 'result of variable lookup or VALUE',
    ...
});

DIAGNOSTICS

none

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

EXAMPLE

SUBROUTINES/METHODS

init

register

escape

TEXT

DIAGNOSTICS

CONFIGURATION AND ENVIRONMENT

DEPENDENCIES

INCOMPATIBILITIES

BUGS AND LIMITATIONS

SEE ALSO

AUTHOR

LICENSE AND COPYRIGHT

Module Install Instructions