NAME

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 $

VERSION

1.04

SYNOPSIS

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

Create a Translator class

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;
}

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

Escape

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

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

{
    escape => 'HTML',
    ...
}

More than one escape
```
<%TEXT ... ESCAPE=HTML|BR%>
```
The 2nd parameter of the method translate (translator class) will set to:
```
{
    escape => 'HTML|BR',
    ...
}
```

VALUE or NAME

Static text values
```
<%TEXT VALUE="some static text"%>
```
The 2nd parameter of the method translate (translator class) will set to:
```
{
    text   => 'some staic text',
    ...
}
```
Text from a variable
```
<%TEXT a.var%>
<%TEXT NAME="a.var"%>
```
The 2nd parameter of the method translate (translator class) will set to:
```
{
    text => $a->var(), # or $a->{var}
    ...
}
```

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

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

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

With a variable

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

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}
}

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

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

{
    text    => 'Hello {name}!',
    gettext => { name => 'world' },
}

With a variable

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

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

{
    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 },
}

Formatter

Allow formatter during initialization.

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

One 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)],
}

Unescaped placeholders

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

With a static value

<%TEXT VALUE="Hello" UNESCAPED_link_begin='<a href="...">' UNESCAPED_link_end='</a>'%>

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

{
    text      => 'Hello',
    unescaped => {
        link_begin => '<a href="...">',
        link_end   => '</a>',
    },
}

With a variable

<%TEXT VALUE="Hello" UNESCAPED_link_begin_VAR="var1" UNESCAPED_link_end_VAR="var2"%>

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

{
    text    => 'Hello {name}!',
    gettext => {
        var1 => $var1,
        var2 => $var2,
    },
}

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,
    allow_unescaped  => $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();

Class method escape

$escaped_string = HTML::Template::Compiled::Plugin::I18N->escape(
    $translated_string,
    $escapes_joined_by_comma,
);

Class method expand_unescaped

$finished_string = HTML::Template::Compiled::Plugin::I18N->expand_unescaped(
    $translated_and_escaped_string,
    $hash_ref_with_placeholders,
);

Subroutine TEXT and swapt out code

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

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

Gettext

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

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

Initialize the plugin and then the template

Create a Translator class

DESCRIPTION

TEMPLATE SYNTAX

Escape

VALUE or NAME

Locale::Maketext placeholders

Locale::TextDomain placeholders

Formatter

Unescaped placeholders

EXAMPLE

SUBROUTINES/METHODS

Class method init

Class method register

Class method escape

Class method expand_unescaped

Subroutine TEXT and swapt out code

DIAGNOSTICS

Text

Maketext

Gettext

CONFIGURATION AND ENVIRONMENT

DEPENDENCIES

INCOMPATIBILITIES

BUGS AND LIMITATIONS

SEE ALSO

AUTHOR

LICENSE AND COPYRIGHT

Module Install Instructions