CGI::Application::Plugin::I18N::Guide - Understanding and using I18N and L10N
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 not be tempted to have a big list or variables or a large hash that you replace based on the users language. This 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.
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. 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
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. 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. Locale::Maketext::TPJ13
These two links will help you understand language tags. http://www.i18nguy.com/unicode/language-identifiers.html I18N::LangTags
UTF-8, you need to understand what this is and why it's used. http://en.wikipedia.org/wiki/UTF-8
You also need to understand the difference between UTF-8 and Perl's internal format. Encode
It's well worth reading Audreys guide. http://search.cpan.org/src/AUTRIJUS/Locale-Maketext-Lexicon-0.50/docs/webl10n.html
Basics bits like yes/no, etc, are provided by:- I18N::Langinfo
Getting deeping into the nitty gritty. Locale::Maketext::Lexicon Locale::Maketext::Simple
And finally:- Locate::Maketext
Now you should have all the background info you need to understand how the CGI::Application::Plugin::I18N module works.
The I18N Catalyst plugin as a Manual page that is full of useful links:- Catalyst::Plugin::I18N::Manual
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:- 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.
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.
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 File menu, then Preferences and select the Parsers tab. You'll see that there is a Perl parser, select this and then click the Edit button.
You'll see that the list of file extensions only has *.pl, extend this so that is contains *.pl;*.pm;*.cgi and any other extensions you use for your applications Perl files. Click OK and OK again.
Now we are ready to create our first catalog. Click File->New catalog. The details I entered:- Project name: Demo Team: po testers Team email: not@now.com Language: English Country: United States Charset: UTF-8 Source code charset: UTF-8
Then select the Paths tab, click the little square graphic for new item then input the path to your script files, I've done /tmp/potest
Then select the Keywords tab and add localtext the same way you added the path.
Click OK to finish, a dialog will ask you where to save your .po file. I selected /tmp/potest/I18N/en-us.po.
You should get a window titled Update summary appear with a list of 4 new strings. Click OK.
If we added another localtext field to the potest example then all we need do is click on the globe icon at the top and it'd parse the files again for new strings.
For this example, click on the Colour string, in the box at the bottom type Color. Now click the save icon. The .mo compiled version of this file is generated automatically on each save.
Ok, now we are ready to test out your .po file and see it in action. Use your browser to open the script potest.cgi.
I'm testing locally on my Vista IIS7. So /tmp/potest for me is actually c:\inetpub\wwwroot\cgi-bin\potest, I'll be opening http://localhost/cgi-bin/potest/potest.cgi in my browser.
You'll get a very basic HTML form asking for a locale, and showing small bits of localized text (I do plan on an advanced version at some point). Enter in en-us and hit submit. You'll see all that has changed is Colour: Colour.
Finally I wont have Americans moaning about how they can't spell colour or cheque properly :P
If you enter in de then you'll get a german example that I've created as an example of a more complete language pack (although my German is minimal, I used babelfish to translate parts so it probably isn't structured correctly).
I haven't used these yet... Stay tuned :)
To install CGI::Application::Plugin::I18N, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CGI::Application::Plugin::I18N
CPAN shell
perl -MCPAN -e shell install CGI::Application::Plugin::I18N
For more information on module installation, please visit the detailed CPAN module installation guide.