1#@!#!123s

22527 1#@!#!123s
: / usr / share / doc / libintl-perl / examples /
Filename : README
back
This is a simple, respectively stupid Perl package that shows how the
complete internationalization process for a Perl package *could* be
done.  It does not claim to be the smartest or the only possible
solution, but it provides at least a skeleton for real packages.  If
libintl-perl should someday become an "established" Perl package, it
would probably be a lot better to seamlessly integrate the process
into ExtUtils::MakeMaker, but for now it's all we have.

The example focuses on the packaging process, i. e. on the things you
have to do to maintain an internationalized Perl package, so that
users of your package will benefit from translations you provide.  It
therefore doesn't make use of any of the nitty-gritty details of
message translation like plural handling or the like.

Requirements
------------

The only requirement is a Perl aware version of GNU gettext.  Perl
support was introduced only recently in GNU gettext, and you will have
to check whether your copy of GNU gettext already supports Perl.  
Support for Perl was introduced in version 0.12.2 of GNU gettext.  If 
your version is older, you have to update GNU gettext.

First test
----------

The subdirectory "simplecal" contains a regular Perl package like the
ones you will find on the CPAN.  You should first try to build and
use the package:

     cd simplecal
     perl Makefile.PL
     make

If you see a warning that the prerequisite Locale::TextDomain is not
found, then you have to install libintl-perl first.

You should never "make install", the package is only a stupid example
and you will not really want to install it.  You can simply try it out
from the installation directory itself:

     perl -Ilib bin/simplecal.pl

It should print a crude calendar representation in English, or even in
your preferred language, depending on your system settings.

The Programming
---------------

Now we should dig into the sources.  All relevant files are commented
and should give you a pretty good idea of what's going on.  Change
your directory to the package directory "simplecal" and inspect the
source files.

The heart of the library is found in the file lib/SimpleCal.pm.  This
Perl module defines functions that map numeric values to month names
or abbreviated week day names.  You will find nothing unusual in this
module except for a line at the beginning of the file that reads:

     use Locale::TextDomain qw (com.cantanea.simplecal);

In case you are not familiar with the operator "qw", this is an
equivalent writing of 

     use Locale::TextDomain ('com.cantanea.simplecal');

That line in the code does three things: It imports the module
Locale::TextDomain, *and* it states that the text domain (or
identifier) for this package is "com.cantanea.simplecal", *and* it says
that the translations for this package can be found in the
subdirectory "LocaleDate" of any component of @INC (unless it can be
found in one of the system locations).  See the POD in
Locale::TextDomain for more information.

You may also find out that some strings have a "__" or a "N__" in
front of them.  The explanation to these funny things has two sides:
First, they mark the following strings as being translatable, so that the
parser "xgettext" included in GNU gettext can find them.  Yet, at runtime
both "__" and "N__" are really function names, and they will look up
their argument in the translation database.  There is more
documentation available on this.  Guess where! Yepp, in the POD of
Locale::TextDomain.

The library is used by a Perl script "bin/simplecal.pl".  Let's have a
look at that script now.  The first remarkable line is the one that
calls POSIX::setlocale():

     setlocale (LC_MESSAGES, '');

The POD of the POSIX module gives additional information on the
function setlocale().  In brief, that call initializes the locale
settings for the category "LC_MESSAGES" to the pre-selected user
settings (this is indicated by the empty second argument).  The
constant LC_MESSAGES is exported by Locale::Messages, which is always
a safe choice.  If your script is only intended to run with Perl 5.8
or better, you can also import LC_MESSAGES from the POSIX module.

The rest of the program only prints a calendar for the current month.
It retrieves the name of the month and the abbreviated weekday names
from our little SimpleCal.pm module which provides this information in
a localized form.

A Dutch Calendar
----------------

We want to see the calendar in Dutch now.  All you have to do is to
set the environment variable LANGUAGE to the value "nl".  If you don't
know how to do this, add the following line somewhere at the top of
"bin/simplecal.pl":

     $ENV{LANGUAGE} = "nl";

Now run the script again:

     perl -Ilib bin/simplecal.pl

It should print out the calendar in Dutch.  Look at the *.po files in
the subdirectory "po" for a list of other translations I have
prepared.  You can try them out in a similar manner.

Please see the file "README-NLS" in subdirectory "sample/simplecal"
for details on how to set the language via environment variables.

The Subdirectory "po"
---------------------

This directory contains the raw translations and a Makefile that will
compile and install them.  If you enter this directory and type "make"
you will see a list of the available Makefile targets.

The first one is the target "pot", a so-called phony target, i. e. it
is not related to a file with the name of "pot".  The command "make
pot" will remake the master catalog of the package and place the
result in the file "com.cantanea.simplecal.pot"
("com.cantanea.simplecal" is the text domain resp. identifier for our
package).  Type the command "make pot" now to see how the master
catalog is actually generated.  If the output says something like
"nothing to be done for `pot'", then delete the file
"com.cantanea.simplecal.pot" and try again.

You should see now that the target file "com.cantanea.simplecal.pot" is
generated by the program xgettext with a plethora of options:

     xgettext --output=./com.cantanea.simplecal.pox --from-code=utf-8 \
              --add-comments=TRANSLATORS: --files-from=./POTFILES \
	      --copyright-holder="Imperia AG Huerth/Germany" \
	      --keyword --keyword='$__' --keyword=__ --keyword=__x \
	      --keyword=__n:1,2 --keyword=__nx:1,2 --keyword=__xn \
	      --keyword=N__ --language=perl && \
     rm -f com.cantanea.simplecal.pot && \
     mv com.cantanea.simplecal.pox com.cantanea.simplecal.pot

Type "xgettext --help" for a detailled explanation of the command line
options.  In brief this invocation causes xgettext to read a list of
files from the file "POTFILES", extract all messages from these
source files and place the result in the output file
"com.cantanea.simplecal.pox".  If the command succeeds, the old ".pot"
file is replaced by the new ".pox" file.

Yes, this is complicated, and that is why this skeleton Makefile is
provided here.  You can copy it without any modification into your
package to use it.

The file POTFILES contains a list of source files to be scanned for
translatable strings.  Have a look at it, and you will understand it.

The Makefile also includes a file called "PACKAGE".  This file contains
all package-dependent information in a couple of Makefile variables:

- TEXTDOMAIN
This Makefile variable should contain the text domain/identifier
for your package.  Please see the POD of Locale::TextDomain for advice
on a reasonable naming.

- LINGUAS
The language codes of all languages supported by your package.  Each 
entry corresponds to a po file in the po subdirectory.

- COPYRIGHT_HOLDER
Usually your name.  Whatever you put here will be included as the
copyright holder in the header of the po files.

- MSGID_BUGS_ADDRESS
Usually your name and e-mail address.  It will also be included in the
po header and translators will check this entry when they come across
a bug in a msgid, or when they have difficulties to translate a certain
message because of awkward coding on your side.

Okay, after "make pot" we have updated the master message catalog
TEXTDOMAIN.pot, in our case "com.cantanea.simplecal.pot".  Have a look
into the file now.  It contains the original English messages that
xgettext has extracted from our source files and blank translations.
The po files (the files the names of which end with ".po") contain
previous translations provided by our package translators.  Whenever
you change the Perl sources, the list of messages may change.  This
results in a maybe new .pot file and requires an update of all po
files.  Try that now and type "make update-po"

You will see confusing output from "make" but you may get the idea
that every single po file (every language that the package supports)
gets updated, and the new strings are inserted into the po
files. Since nothing really changed here (we did not change the source
files yet) you can now try to update the compiled po files which end in
".gmo" (for GNU mo format) with "make update-mo".

Again, you will see maybe cryptic output from "make" that signifies
that all compiled files are re-generated now by a program called
"msgfmt".

The last step requires that you copy the (possibly changed) mo files
into your package by "make install".  This will copy the gmo files as
".mo" files into the subdirectory "LocaleData" of your package so that 
libintl-perl is able to find them at runtime.

You can perform all these steps at once by typing "make all" although
this is mostly useful for testing purposes.  In reality the workflow
is different:

- You change your source files, messages may have been added, deleted
  or modified.  You will have to update the master message catalog by
  typing "make pot".

- Since the translations may have gotten out-of-date, you will have to
  merge your changes into all po files by "make update-po".

- Your translators will get copies of the po files, reflect your
  changes in the po files and send them back to you.

- When you have received the updates, it is time to compile the po
  files into a binary representation with "make update-mo".

- These binary mo files have to be installed under "LocaleData", and
  you have to "make install".  Note that "make install" installs the
  mo files in your source package, not in the system location!

- Now that you have updated the translations for your package, you
  will want to upload a new version to the CPAN.

Note that all these steps are *only* necessary for package
maintainers.  As a user of the package, you will only see the
resulting mo files under "LocaleData".  End users do *not* need any of
the gettext tools, and they do not have to perform any of the above
steps theirselves!

Changing the Sources
--------------------

You may wonder whether your translators have to re-translate
everything from scratch whenever you change your Perl sources.  This
is, of course, not the case.  Let's say, you want to add a welcome and
a good-bye message to the program output.  Have a look into
"bin/simplecal.pl" and you will see that this is already prepared but
commented out (search for "Welcome to" and "Bye" if you can't find
it).  Uncomment these lines and see what happens to the po files in
that case.

Before you proceed, you should have a look at the Dutch translation
file "nl.po".  At the bottom you will find some lines that are
commented out with "#~" and that proove that I have already prepared
that case.  The comment sign "#~" in po files signifies that a
particular translation is obsoleted, i. e. no longer needed because it
is no longer present in the source files.

Say, that you have really changed your mind, and you want to
re-introduce the welcome and good-bye messages to your program and you
uncomment the corresponding lines in "bin/simplecal.pl".  You will
have to re-make the master catalog "com.cantanea.simplecal.pot" by
"make pot", and then "make update-po" to update the po files.  In
fact, "make update-po" is sufficient because it will also update the
pot file if it is out-of-date (i. e. if any of the source files have
changed in the meantime).

Type "make update-po" now, and look again at "po/nl.po".  You will see
that the previously translated welcome and good-bye messages have been
re-activated from the obsoleted entries.  In fact your translators
will have nothing to do, because their old translations are still
valid.  Type "make install" and then re-run "perl -Ilib
bin/simplecal.pl", set the environment variable "LANG" to any of the
available languages, and things will still work perfectly.

Of course, it is a rare case that messages are discarded and later
re-activated in programming sources.  It is more likely that you will
modify a message, or maybe add a message that is similar to former
ones.  Let's say that you want to change the exclamation mark in the
good-bye message at the bottom of the script to a simple full stop.
Look for the line that reads

     print __"Bye!\n";

and change it into

     print __"Bye.\n";

Change into the directory "po", update the translation files with
"make update-po" and inspect the file "nl.po".  At first glance, you
may not see any change.  But then: The entry for the good-bye message
has an additional comment "#, fuzzy".  The fuzzy mark signifies that
the msgerge program has found that a message is very similar to a
previous message (even obsoleted ones are taken into account), and
that it proposes an old translation here.  The translator will
normally modify the translation accordingly (without having to re-type
everything), remove the fuzzy mark and send back the translation to
you.

In fact you could also install translations that have not been revised
by the translator and are still marked as fuzzy.  This is not
recommended however! The algorithm used in msgmerge is quite smart
and seldom fails to detect minimal changes in the source message and
propose the old translation.  However, it often proposes translations
from other valid or obsoleted entries that are only vaguely related to
the real meaning.  You should understand the fuzzy merging mechanism
as a helpful feature to the translator only and never install fuzzy
translations unless you absolutely know what you are doing.

Pass Comments to Translators
----------------------------

The po files contain references for every message to the corresponding
source files as comments.  But you still may feel a need for giving
hints to the translators.  You may want to tell the translators, that
the good-bye message can be somewhat sloppy (or whatever you like).
This is simple to do.  Have a look at the good-bye message in
"bin/simplecal.pl" and you will see that it is preceded by a comment
introduced with the string "TRANSLATORS:".  If you start your Perl
comment like this, it will end up as a comment for translators in the
resulting po (resp. pot) file and may serve as a hint for translators.

In fact, the string "TRANSLATORS:" is arbitrarily chosen.  If you
prefer another string, change it in the invocation of "xgettext" in
the skeleton Makefile provided here.

Informational Files
-------------------

You should put two additional files in your distribution.  The first 
one is "README-NLS".  It should be a verbatim copy of the most recent
version found in the "simplecal" sample package.  Please send 
corrections or improvements to this file to the maintainer Guido
Flohr <guido.flohr@cantanea.com>, and add package-specific notes to your
documentation instead.  Users expect this file to have a standard
contents, and they will not check it for changes on a regular basis.

The file "TRANSLATIONS" should reflect the current translation status
of your package.  It should list all currently availabe translations,
their completeness, and it should also inform your user which translations
are actively maintained, and which are not.  You can find a sample
in the "simplecal" sample package. 

Bringing It All Together
------------------------

The above sounds definitely more complicated than it is.  In practice
you code as before but mark all your strings with "__" and friends
like described in the POD of Locale::TextDomain.  Before a new release
you change into the directory "po" of your distribution and type "make
update-po" to update the available translations.  Distribute the
modified po files to your translators, and once you have collected
them all, type "make install" to add them to your distribution.

That's all, all translations will be available in your package now.

Internationalizing Existing Packages
------------------------------------

Internationalizing an already existing package with libintl-perl is
less painful than you think.  The following roadmap should do it with
minimal effort.

First create a subdirectory "po" in your sources, copy the "Makefile"
from this sample, and copy and edit the files "TEXTDOMAIN" and
"LINGUAS" (LINGUAS can set the Makefile variable "LINGUAS" to the
empty string and TEXTDOMAIN should set "TEXTDOMAIN" to a name as
advised in the POD of Locale::TextDomain).

Next you have to mark the translatable strings in your sources with
"__" and friends.  You can do that by hand, but isn't that the kind of
job that you have bought a computer for?  List your source files in
"po/POTFILES" and then try

     xgettext -a --files-from=POTFILES -o all.pot

The option "-a" instructs xgettext to extract *all* strings from your
sources.  This option may miss a few strings (consider a bug report in
that case), it will issue a lot of warnings about "illegal variable
interpolations" (see the POD of Locale::TextDomain for workarounds)
and will put a lot of strings extracted from your sources into the
file "all.pot".

Now, load the file "all.pot" into an editor of your choice.  If your
choice is "GNU emacs" you will have maximum comfort: Select an entry,
type "s" and you can cycle through the source files that this
particular entry originates from.  Other PO editors like KBabel or
PO-Edit provide similar functionality.  But even with the "Notepad" on
MS-DOS you will be able to navigate to the corresponding source file.
Once you have found the origin in your sources, you have to decide
whether this is a false positive, and you simply ignore it.  If it is
a translatable string you either simply mark it with "__" or you
"repair" it.

What does "repair" mean? Again, the POD of Locale::TextDomain... In
brief: Your Perl sources will be full of stuff like:

     die "Cannot open file '$filename': $!\n";

This string is not suitable for translation, because it is not
constant.  It may change depending on the value of the variable
$filename and the value of $!.  You will have to change that into
something like:

     die __x ("Cannot open file '{filename}': {err}\n",
              filename => $filename, err => $err);

Once you are done with marking the strings, you can try to run your
scripts/modules and you will see a lot of complaints by Perl that it
doesn't know about "__" (in various incarnations).  Remember that "__"
is really a function call and you have to import the function "__" and
its relatives into your namespace.

What you have to do is to invent an identifier for your package (see
Locale::TextDomain for hints) and then add the following line to all
of your source files that produced errors:

     use Locale::TextDomain ('Name-Of-My-Package');

You will be happy if "Name-Of-My-Package" is the same as the Makefile
variable "TEXTDOMAIN" in the file "po/TEXTDOMAIN" that you have
created in the beginning.

For the common case of a pure library: Is that really all I have to
do? Yes! What about POSIX::setlocale(), don't I have to make a call
somewhere? No, not for a library! And what about calls to textdomain()
and bindtextdomain() that I know from C or other languages? No, this
is all hidden in "use TextDomain (PACKAGENAME)" for Perl.

To make it clear again: A library should NEVER change the locale
settings.  The script that uses a library (or multiple libraries)
should do that, and this boils down to three lines of Perl:

     use POSIX qw (setlocale);
     use Locale::Messages (LC_MESSAGES);

     setlocale (LC_MESSAGES, "");

That means: The *calling* Perl script, the one that uses possibly
internationalized libraries, should initialize the locale settings to
the user preferences.  Libraries should honor that setting but should
never change it.  If a script misses a call to setlocale(), your
internationalized library will happily continue to work flawlessly
with the original English messages, it is up to the client programmer
to reveal the i18n features in your code!

Good luck!

Guido