Steffen Winkler
and 1 contributors

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

SEE ALSO

HTML::Template::Compiled

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.

AUTHOR

Steffen Winkler

LICENSE AND COPYRIGHT

Copyright (c) 2009 - 2010, Steffen Winkler <steffenw at cpan.org>. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.