


                     Localization (l10n) for CAT
                     ===========================

    Copyright (C) 2009 by Christian Kuelker - 2009-12-31 version 0.1


Abstract: This document describes the process of making CAT core or CAT custom
modules language-translation aware. This called localization (l10n). Or to put
in simple words: what you have to do to get your piece of code translated. If
you just want to translate or add a new language to a module which is already
localized, you should skip this document and read i18n.txt instead.


Contents
========

  1   Preface

  2   Localization of CAT and custom CAT-Modules - Perl code
  2.1 For CAT core modules
  2.2 For CAT custom modules

  3   Localization of CAT HTML templates via Template Toolkit 2
  3.1 For CAT core modules
  3.2 For CAT custom modules

  4   Create or update the po template: messages.pot


1   Preface
===========


2   Localization of CAT and custom CAT-Modules - Perl code
==========================================================


2.1 For CAT core modules
========================

For CAT core modules, which are released with CAT directly this is needed:


    # include the base class
    use base qw(CipUX::CAT::Web::L10N);

    # and later
    $lh->maketext('Hello World!');


2.2 For CAT custom modules
==========================

For a custom module it is important to load own translation under a custiom
domain in addition to the code which is ordinary CAT module uses.

    # include the base class
    use base qw(CipUX::CAT::Web::L10N);

    # and then
    $self->import_lexicon({domain=>'userlist'});

    # and later
    $lh->maketext('Hello World!');

All parts from the former section are needed and then the module needs to find
all *.po files.

    # new BUILD and INSTALL target (lib/*/*.po)
    # (will install all po files under lib)
    $builder->add_build_element('po');

Add this at the end of the custom Build.PL.

Secondly, it is important to provide a po template file, for example
messages.pot. Create a special directory for this:

    cd <custom-module>/lib/CipUX/CAT/Web
    mkdir I18N
    mkdir I18N/<custom-domain>

Replace <custom-module> with the module name and <custom-domain> with a new
canonical domain name.

Example for CipUX-CAT-Web-Userlist-3.4.0.2

    cd cat-web-userlist/lib/CipUX/CAT/Web
    mkdir I18N
    mkdir I18N/userlist



3   Localization of CAT HTML templates via Template Toolkit 2
=============================================================

3.1 For CAT core modules
========================

If you found a non-translated string or sentence inside an HTML page, which
will be processed by template toolkit (the default) you have to add a template
toolkit macro.

Example: You find this sentence:

   <h1>Hello World!</h1>

Then you change it the following

    <h1>[% lh.maketext('Hello World!') %]</h1>

If the interpolation of variables is necessary in the template

    <p>[% lh.maktext(m.NAME) %]</p>

then this will first evaluate m.NAME to 'class' for example and then ask
Locale::Maketext for the internationalization for 'class' which will be
'Klasse" in the case of the 'de' tag. One problem might rise for this behavior,
how will the message id for 'class' get into the messages.pot file, since
automated grabbing for maketext strings in the source code and HTML will never
find that id?  To solve that we have to make a dummy page for that in CAT. This
page called translation.html and will contain such automatic message ids. If a
new module generates such messages id, or if a still untranslated message id is
found, it should be added to the translation.hml file as a table line.

    <tr><td>class</td><td>[% lh.maketext('class') %]</td></tr>


3.2 For CAT custom modules
==========================

The principle is the same as 3.1 describes. additionally you have to ensure
that the Locale::Maketext object $lh is exported to your template.

    lh => $lh

If you use the CAT standard way you can do that in the param_hr section of your
return hash.


Example:


    sub module {

        my ( $self, $arg_r ) = @_;
        my $lh = $arg_r->{lh_obj}; # get obj from Controller
        # you need to do this if you want your own object:
        # use CipUX::CAT::Web::L10N;
        # my $lh = CipUX::CAT::Web::L10N->get_handle;

        return {
             layout => "$path/layout.html",
             layout_ar => [
                 { begin_html => 1, },
                 {
                     tt2_hr => {
                         tpl      => "$path/index.html",
                         param_hr => {
                            DATA       => \@tpl_data,
                            lh         => $lh,
                        },
                    }
                },
                { end_html       => 1, },
            ],
        };
    }



4   Create or update the po template: messages.pot
==================================================

This template already exist for CAT core modules. However sometimes it needed
to be updated. The command for creating the template and for updating the
template is the same. The difference between CAT core and custom module templates
are just the location.

    CAT core module    -  lib/CipUX/CAT/Web/I18N/messages.pot
    CAT custom module  -  lib/CipUX/CAT/Web/I18N/<custom-domain>/messages.pot


The location of that file have to match the chosen custom domain of CAT custom
modules. If the domain would be 'userlist' the location is:

lib/CipUX/CAT/Web/I18N/userlist

Create this structure if necessary. If correct Locate::Maketext calls are
present - like lh.maketext('Something') in templates or
$lh->maketet('Somthing'); in Perl code - the po template can be created by

Example (Perl modules only)

   cd <custom-module>
   export XGT=/usr/share/doc/liblocale-maketext-lexicon-perl/examples/xgettext.pl
   export DOM=<custom-domain>
   export OUT=lib/CipUX/CAT/Web/I18N/$DOM/messages.pot
   perl $XGT --output=$OUT --directory=lib/

Because xgettext.pl tends to evaluate also *.png files we have to make sure
that they are not scanned. A simple --directory=tpl would not do it.

Example for 'userlist':

   cd cat-web-userlist
   find lib -name "*.pm" > doc/maketext.files
   find tpl -name "*.html" >> doc/maketext.files
   export XGT=/usr/share/doc/liblocale-maketext-lexicon-perl/examples/xgettext.pl
   perl $XGT -g -u -o lib/CipUX/CAT/Web/I18N/userlist/messages.pot -f doc/maketext.files


The next step is to deal with internationalization (i18n). Adding the first
translated language ans so on. Please proceed with i18n.txt.


