Back to Top

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 $

Back to Top

VERSION

1.04

Back to Top

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

Back to Top

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.

Back to Top

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

Back to Top

EXAMPLE

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

Back to Top

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

Back to Top

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

Back to Top

CONFIGURATION AND ENVIRONMENT

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

Back to Top

DEPENDENCIES

Carp

English

Hash::Util

Data::Dumper

HTML::Template::Compiled

HTML::Template::Compiled::Token

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

Back to Top

INCOMPATIBILITIES

not known

Back to Top

BUGS AND LIMITATIONS

not known

Back to Top

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.

Back to Top

AUTHOR

Steffen Winkler

Back to Top

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.

Back to Top