Mozilla in Klingon, Sindarin and even in your language

------------
NOTE: A quick po2moz update has been added to the end to cover packaging the
translated PO files.

Also see:
http://www.mozilla.org/projects/l10n/mlp.html

Mozilla now has a localisation trademark policy.  [opinion]Seems like Free
Software get restricted after all.  Now if they had only cared abotu l10n from
teh beginning and followed processes seen in KDE and Gnome they wouldn't have
this problem at all.[/opinion]

Read the l10n policy here:
http://www.mozilla.org/foundation/trademarks/l10n-policy.html
http://www.mozilla.org/foundation/licensing.html
------------

Everyone who had some contact with great Open Source projects knows that
localization and internationalization are really important and even
essential in places like the France or Italy. The Mozilla project have a
nice L10N team but the tool that everybody actually uses isn't so helpful
to create a colaboration method about the translations.

If you want to translate some portion of the suite, say the ChatZilla, you
need to download the latest Mozilla Translator release (dated from 2002),
install the Java SDK, study how it works and then start to translate it.
But, you can't easily merge two translations packs into MT what means is
really hard to more than one person to translate something. At least is
that what we from Mozilla Brasil have noticed.

Some greatest projects like KDE and GNOME uses by default the POT format to
translate its files and they do a fast and simple job. What do you think
to use it to translate the T-Rex? You could even to use the Kbabel or
something other popular tool to translate from Mozilla's DTD files. But
wait, a DTD file is not a .POT! Foremost we need to understand every term
used:

- POT: this term means Portable Object Template and this file format is the
one used by a great ammount of projects to translate its interface. If you
know something about the GNU/Gettext library you know what I'm talking
about. These template files have the original messages and the field to be
filled with the new translation (respectively, msgid and msgstr).

- DTD: this is the file format used by Mozilla to store its messages and
means Document Type Definition. If you open up some Mozilla's DTD file you
can find a lot of <!ENTITY.

Your problems handling that kind of things can be done using the Translate.
Translate is the new mozpotools, a kit of GPL Python scripts that can be
used to convert DTD files to the POT format and also can do the reverse
operation. In fact it converts the files to PO, but there's no a big
difference between .pot and .po files.

Actually the kit of scripts Translate can be found at SourceForge and you
just need to have Python 2.3 (be sure to have the development package
too). To be able to use them, you have to get the CVS files first (a 0.4
packaged version is coming soon):

	bash$ cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/translate
login
	bash$ cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/translate
co src

Just press ENTER when asked for the password. After that you'll have a /src
directory, and entering on it you will see the setup.py script. To see all
the options use:

	bash$ ./setup.py --help-commands

Take a look at the build and install option. You need to run the script
with them to have the tools installed and easy to use:

	bash$ ./setup.py build ; ./setup.py install

Now you have the moz2po and po2moz binaries under your /usr/bin/ directory
and some extra files inside /usr/lib/python2.3/site-packages/translate/.
Let's try it! I suggest you to make a separated directory to that. First
then copy the en-US directory from your Mozilla distribution to it. This
en-US directory will be the template one used by the script to convert the
DTD files. I'm assuming the pt-BR name because I'm brazilian, but it could
everything you want:

	bash$ mkdir pt-BR ; cp -R /home/you/mozilla-1.6/chrome/en-US/ .

Note that I got the en-US directory from a uncompressed package like
mozilla-1.6-xft-gtk2-pc-linux.tar.bz2. You could get it from the en-US.jar
file that is inside your chrome anyway; it's a ZIP file, just rename it
and unzip then, or even open it in the Konqueror file manager that have
built-in support for it. Also, you could get this en-US directory from any
Mozilla project, say the Checky extension hosted at MozDev.

Now it's time to convert finally the DTD files inside this en-US to the PO
format, to be stored inside the pt-BR directory. You can see all the
options of the scripts in the end of this document, but let's go to the
nice part of it using a detailed progress bar:

	bash$ moz2po --progress=verbose -i en-US/ -o pt-BR/

Now you have the pt-BR directory filled of .po files converted from
the .dtd
ones and also from the .properties! If you check some of them you'll find
strings like these:

	#: windowtitle.label
	msgid "About Popups"
	msgstr ""

You just need to open it in some decent translation editor like Kbabel or
the
Gnu/Emacs with the PO Mode - in fact, you could even use VI. If you don't
know how to translate a .po file, just hit the TLDP web site or the KDE
Developers area, since this document doesn't explain how to use Kbabel or
how to edit the .po strings. But don't worry, it's really easier to do
than when using Mozilla Translator. Check the end of this text for some
interesting links about that.

Okay, you are a smart person and have distributed some .po files to a
certain
ammount of people so that they could translate the respective strings and
then resend it to you already in portuguese (in this case, like said
before).
You so need to do the reverse operation, converting the PO files to the DTD
format, to be able to packing it and make your own .xpi or a entire
localized build:

	bash$ po2moz --progress=verbose -i pt-BR/ -t en-US/ -o NEW/

In the line above, the input directory is in portuguese, using the original
en-US as its DTD template and outputing it to the directory NEW, to be
renamed to pt-BR, when it is deleted.

Great job! You have done the converting/translating/reconverting way. I
think this document can be useful to you, so that you could easily and
colaborative translate the Mozilla softwares to your native language or
even so to Klingon or Sindarin... nice, uh?

Caio Begotti entercaio@uol.com.br
Mozilla Brasil http://www.mozilla.org.br

Full options:

For the setup.py script inside the /src directory mentioned before:

~/translate/src: ./setup.py --help-commands
Standard commands:
  build            build everything needed to install
  build_py         "build" pure Python modules (copy to build directory)
  build_ext        build C/C++ extensions (compile/link to build directory)
  build_clib       build C/C++ libraries used by Python extensions
  build_scripts    "build" scripts (copy and fixup #! line)
  clean            clean up output of 'build' command
  install          install everything from build directory
  install_lib      install all Python modules (extensions and pure Python)
  install_headers  install C/C++ header files
  install_scripts  install scripts (Python or otherwise)
  install_data     install data files
  sdist            create a source distribution (tarball, zip file, etc.)
  register         register the distribution with the Python package index
  bdist            create a built (binary) distribution
  bdist_dumb       create a "dumb" built distribution
  bdist_rpm        create an RPM distribution
  bdist_wininst    create an executable installer for MS Windows

usage: setup.py [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
   or: setup.py --help [cmd1 cmd2 ...]
   or: setup.py --help-commands
   or: setup.py cmd --help



For the moz2po script localized under your /usr/bin/ directory:

bash$: moz2po --help
usage: moz2po [options] [--version] [-h|--help] [-i|--input INPUT]
[-t|--template TEMPLATE] [-o|--output OUTPUT] [--progress PROGRESS]

options:
  --version             show program's version number and exit
  -h, --help            show this help message and exit
  -iINPUT, --input=INPUT
                        read from INPUT dir in properties, dtd formats
  -tTEMPLATE, --template=TEMPLATE
                        read from TEMPLATE dir in properties, dtd formats
  -oOUTPUT, --output=OUTPUT
                        write to OUTPUT dir in po format
  --progress=PROGRESS   set progress type to one of simple, console,
verbose,
                        curses
  -P, --pot             produce PO template (.pot) with blank msgstrs



For the po2moz script, used to reconvert from .po to .dtd:

~/Desktop/CVS-translate/src: po2moz --help
usage: po2moz [options] [--version] [-h|--help] [-i|--input INPUT]
[-t|--template TEMPLATE] [-o|--output OUTPUT] [--progress PROGRESS]

options:
  --version             show program's version number and exit
  -h, --help            show this help message and exit
  -iINPUT, --input=INPUT
                        read from INPUT dir in po format
  -tTEMPLATE, --template=TEMPLATE
                        read from TEMPLATE dir in po format
  -oOUTPUT, --output=OUTPUT
                        write to OUTPUT dir in properties, dtd formats
  --progress=PROGRESS   set progress type to one of simple, console,
verbose,
                        curses



References:

http://l10ntools.mozdev.org
http://www.mozilla.org.br
http://translate.org.za
http://www.mozillatranslator.org
http://www.mozdev.org
http://tldp.org
http://i18n.kde.org/translation-howto/
http://www.mozilla.org/projects/l10n/
http://l10nzilla.mozdev.org

Local references:

man gettext (quick manual)
info gettext (detailed information)

Micro-Faq:

1. How could I merge two directories with different languages so that I
can get a set of files with both english and my native language strings?

In the past Translate used to have a script called repot.py to do this
kind of job, but right now you can use normally the scripts available
using your language DTD directory as the input files and the original
en-US DTD directory as the template:

	bash$ moz2po --progress=verbose -i your_language -t en-US -o merged_files/

Then you will get inside the merged_files/ directory a lot of .po files
with both the msgid/msgstr like that:

	#: windowtitle.label
	msgid "About Popups"
	msgstr "Bloqueando popups - Mozilla"

Note that in this example, the msgstr is in brazilian portuguese, but
it could be in any language and all the msgid are the original strings.

2. I never had used Kbabel to translate anything! Help me?

Although the Translate kit convert DTD files do the format that Kbabel
handle we can't give any kind of support about it. Please check the
links section of translate.sf.net to see pages that teaches you how to
use Kbabel.

3. I'm a Windows user: does it means I'll never be able to use the .po
format and help my local team with translations?

Absolutely not! There is a interesting .po editor for Windows called poEdit.

4. Okay, your kit is great but I have no clue about what must be done
to create my own .xpi package. What now?

Of course you did read the MLP instructions about this situation, right?
Please go to http://www.mozilla.org/projects/l10n/ to see more information
about how to create .jar files or .xpi packages.

REVISED
-------

The following are revisions that ideally need to be integrated into the
document above or into Javier SOLA's documentation.  They are here as a
temporary measure to assist those packaging Mozilla.

Asumption: You are either using a prepacked version of the Mozilla POT files
(these apply to version of Mozilla 1.7.3 and above, and those above 1.8a2) or
are using the CVS version of the files.

YOu have completed translation of the files into your language or have migrated
older translations to the newer POT files.

Packaging is now quite simple you need to follow these steps:

1) Make sure you have a copy of the en-US language XPI
2) Localise the sections in package/install.js to suite your language
3) Copy all .rdf files into you translation directories.  Change all reference
   to en-US to your 'lang-REG' eg 'af-ZA' for Afrikaans South Africa.  Also
   change entries listed and 'English (US)' to your language.
   You can safely delete any RDF files that you did not change.

Now you are ready to proceed with the packaging:

  po2moz -laf-ZA -t langenus.xpi af/ mozilla-1.7.3-afrikaans.xpi

Where:
	-l is the locale for your language and region
	-t is the template or original English (US) XPI
	af/ contains all the localised files
	mozilla-1.7.3-afrikaans.xpi - is the new language pack.  We choose to lable
		is like this to ensure that we can distinguish between various products
		that we localise eg firebird.  That the version is clear.  And that the 
		language is shown in a human readbale format.

Now upload and test before releasing.

TODO: Who to notify when we have a build that should be on Mozilla.org