PURPOSE AND UTILIZATION OF THE TOOLBOX
======================================

This toolbox is expected to facilitate and secure work of maintainers and
translators:
(1) in providing wrappers to gettext commands, so that users do not have
    to remember syntax and usage of each one of them,
(2) in insuring that these commands be used consistently by all contri-
    butors, to ease communication between them and quality checking.

Provided Documentation will allow involved people to familiarize
themselves with concepts and processes of shell scripts' internationa-
lization and localization before using this toolbox.

All needed stuff, including the toolbox itself, are expected to be located
in a directory name localization, with this content:

localization
localization/docs
localization/docs/Workflows
localization/docs/Help
localization/docs/Utilization
localization/docs/i18n_scripts
localization/docs/i18n_scripts/1_PRESENTATION
localization/docs/i18n_scripts/2_DIAGRAMS
localization/docs/i18n_scripts/6_TRANSLATORS
localization/docs/i18n_scripts/5_MAINTAINERS
localization/docs/i18n_scripts/4_LOCALIZATION
localization/docs/i18n_scripts/3_INTERNATIONALIZATION
localization/tmp
localization/scripts
localization/po
localization/wip
localization/toolbox.sh
localization/name

The scripts to be internationalized are stored in 'scripts'

'name' is text file containing just the name (without .po or.pot suffix)
of the source file that will gather messages to be translated extracted from
the scripts in 'script'.
For instance if the source file should be slint.pot, name should contain
only the name slint.
'wip' gathers files to be checked. After having checked them move them
to 'po'

Features of the toolbox are presented below.

make_POT: generates a (new) POT file
====================================
This feature is to be be used whenever a script to be localized is added,
updated or deleted

The maintainers generates the POT file which is stored in ./wip

This should trigger usage of init_PO or merge_PO feature by the translators.

check_xtract: check extraction of text scripts' messages in the POT file
========================================================================

This feature is to be used by the maintainers whenever a text script is
first internationalized, or updated once internationalized.

The goal is to make sure xgettext extracts every marked message. Errors
listed are generally caused by a failure to comply to one of xgettext's
requirements.

init_PO: initialize a PO file for a given locale
================================================

This feature is to be used by te translators whenever a new localization
is initiated.

The new PO file is then edited by the translators to translate all
messages.

Usage of a specialized PO editor for PO's editing is highly recommended.

init_PO is intended to be used only once per locale.

In case a PO file needs to be updated to follow up the release of an
updated POT file, the merge_PO option is to be used instead.

Before the fully translated PO file be handed over to the maintainers, it
is mandatory to check it using the check_PO option.

check_PO: check that all messages are translated in a PO file
=============================================================

This option is to be used before a PO file be handed over to the
maintainers and the MO file for the same locale be generated.

format_PO: generate a MO file for a given locale
================================================

This feature is provided to for testing purposes, whenever a PO file has
been edited.

merge_PO: update a PO file following an update of the POT file
=============================================================

This feature allows to update the PO file if the source files itself
has been updated, prior to editing to updated the modified messages and
tranlsat ethe new ones

In that case the maintainers, after having updated the POT file, inform
translators to use this feature.

Each translator will then update the PO file using a PO editor, check
it, then hand it over to the maintainers.


Didier Spaier