view release on metacpan or  search on metacpan

lib/CGI/Application/Plugin/I18N/Guide.pod  view on Meta::CPAN

=head1 NAME

CGI::Application::Plugin::I18N::Guide - Understanding and using I18N and L10N

=head1 BACKGROUND

I'm writing this guide for people who find themselves in the position I did.
You code Perl CGI scripts, you want to make your scripts more open to other
countries, and thus other languages. How is this done? Well after much research
this is best done properly, do B<not> be tempted to have a big list or variables
or a large hash that you replace based on the users language. This B<will>
quickly break and do nothing more than to annoy people including yourself.

Have a read through this guide. If you are completely new to
Internationalization then you'll find this guide and it's resources useful even
if you aren't using CGI::Application.

=head1 WHERE TO START?

Internationalization of your application or I18N for short, means making your
application language packable. So that Localization (L10N) can be done for the
end user. Depending on the language your are localizing to, these language
packs can become complicated. If you are unfamiliar with the structures of
other languages you'll probably be surprised (as I was) as to just how much
things can differ, not just in alphabet and sentence structure, but culture,
what's exceptable, varying degrees of quantifiers, not to mention currency
formats!

I don't want to re-write all the stuff that's been covered before. So before
you continue on this guide, catch up your reading on the following resources.
B<Note: I recommend reading pretty much everything, this isn't the easiest
subject to get your head around. Trying to skip ahead may well mean having to
re-read it all again later>

=head2 Things to read

This is the order I recommend:-

We'll start with what's pretty mcuh the current standard for localization:
Gettext, I'd only read to section 1.5, but feel free to read more if you are so
inclined.
L<http://www.gnu.org/software/gettext/manual/gettext.html#Introduction>

This'll cover some of the issues and ideas with the differences between
languages and some ways around them.
L<Locale::Maketext::TPJ13>

These two links will help you understand language tags.
L<http://www.i18nguy.com/unicode/language-identifiers.html>
L<I18N::LangTags>

UTF-8, you need to understand what this is and why it's used.
L<http://en.wikipedia.org/wiki/UTF-8>

You also need to understand the difference between UTF-8 and Perl's internal
format.
L<Encode>

It's well worth reading Audreys guide.
L<http://search.cpan.org/src/AUTRIJUS/Locale-Maketext-Lexicon-0.50/docs/webl10n.html>

Basics bits like yes/no, etc, are provided by:-
L<I18N::Langinfo>

Getting deeping into the nitty gritty.
L<Locale::Maketext::Lexicon>
L<Locale::Maketext::Simple>

And finally:-
L<Locate::Maketext>

Now you should have all the background info you need to understand how the
L<CGI::Application::Plugin::I18N> module works.

=head2 Other useful resources

The I18N Catalyst plugin as a Manual page that is full of useful links:-
L<Catalyst::Plugin::I18N::Manual>

=head1 Creating .po and .mo files

The .po files are the editable language packs. The .mo files are compiled
versions that are a bit faster to use.

I've found a good little app for creating .po and .mo files:-
L<http://www.poedit.org>
It's cross platform and gives you a nice GUI to work from. Of course you can
always edit the .po files direct and generate the .mo files yourself.

=head2 Getting the sample files

This module includes some sample files in the folder sample/poedit. It's a tiny
CGI::Application script designed to get you used to using and editing .po files.
You'll need to copy this folder to your webservers public folder. It's safe to
do this by FTP is you are stuck on shared hosting. Or you can test locally,
just copy the folder to your public_html, httpdocs, wwwroot, etc. Depending on
your servers configuration you might have to put this in the cgi-bin. For the
sake of simplicity the rest of this guide refers to this folder as /tmp/potest.

=head2 Using Poedit

Download and install Poedit. When you open for the first time it'll ask for
your name and email, don't worry this is just for stamping the .po files with
your details.

Click the I<File> menu, then I<Preferences> and select the I<Parsers> tab.
You'll see that there is a Perl parser, select this and then click the I<Edit>
button.