# For maintainers: maintaining internationalized &d-i; packages

## &d-i; packages internationalization and localization

The &d-i; packages use a `debconf`-managed interface to handle user interaction screens and all display.

The debconfized packages use `po-debconf` for handling localization which means that templates translations are hosted in directories named `debian/po` in each package source code tree.

These directories contain `<language>.po` files where <language> is the code of supported languages. See language-codes for details about language codes.

They also contain a file named `templates.pot` which contains up-to-date strings. This file is generated by the `debconf-updatepo` utility when debconf templates are modified or written.

When working on "core" &d-i; packages, developers should not care about the `debian/po` directory contents. They even don't need running the `debconf-updatepo` utility, except the first time they create the package (so that the `debian/po/templates.pot` file is created).

The only files that are not automatically generated in `debian/po` are:

- `debian/po/output` defines the type and encoding of the generated `templates` file. The file must always contain:

      2   utf8

- `debian/po/POTFILES.in` defines the file containing the source strings, with a path relative to the `debian` directory of the source tree. This is usually:

      [type: gettext/rfc822deb] <package>.templates

  where <package> is the name of the binary package using these templates.

## English templates handling

### General recommendations

&d-i; developers are strongly encouraged to read the po-debconf(7) man page and must have a good knowledge of `po-debconf` mechanisms. Please ask for advice in the &email-debian-boot-list; mailing list when in doubt.

Templates files must be named `<package>.templates`. Developer should not use files named `debian/templates` though `debhelper` scripts properly handle such files. This requirement has been added because the translators work on a general file which groups together all templates from all &d-i; packages. This general file mentions, for each string, the originating file name. If this file name contains the package name, the translator will then know which package the string (s)he translates belongs to.

### New debconf templates introduction

Maintainers must respect the Debconf Templates Style Guide (DTSG) (see the Debian Developers Reference, chapter Best Packaging Practices, section General recommendations for authors and translators) and the general style for writing templates for &d-i; (a special section of the DTSG mentions &d-i; templates). In any case, before committing new templates or templates changes, these templates must have been reviewed by other &d-i; developers.

Committing templates with incorrect English or templates with a different writing style than the general &d-i; writing style could trigger nearly immediate translation work. These translations will later need to be adapted again when the strings are corrected.

For that reason, new templates for an existing &d-i; package should initially be marked as non translatable. This is done by not prepending the templates fields with an underscore character. Example:

    Template: debian-installer/foo/bar
    Type: note
    Description: New note.
     This is a completely new note, added for package foo.

New &d-i; packages with debconf templates do not need this. Their templates may be marked as translatable because these packages are ignored by the synchronisation scripts until they are added to the `packages/po/packages_list` file (synchronisation-scripts).

After adding the new templates or the new package, maintainers must request for peer review in &email-debian-boot-list;.

New packages will be added to the master files only when this review will have been completed.

### Marking strings for translation

Strings which need translation must be prepended by a leading underscore (_) character in the `templates` files.

After the strings review, the templates must be marked for translation by prepending their field with an underscore character:

    Template: debian-installer/foo/bar
    Type: note
    _Description: New note
     This is a completely new note, added for package foo.

Then, the synchronisation scripts will automatically add the two new strings to the translators file, allowing them to work on translations.

## Translators work method

This paragraph describes the master file process. It is included in the chapter aimed at package maintainers because it appeared important that &d-i; package maintainers understand the way translations are handled.

All PO files from all packages sitting under the `packages` directory of the &d-i; source tree are merged into one single file and translators update this file. These so-called master PO files are kept into `packages/po` into the &d-i; main directory.

These files are the only files managed by translators. All other PO files as well as PO "templates" files (POT files) are automatically generated by the synchronization scripts (see synchronisation-scripts):

- merge all `templates.pot` files into `packages/po/template.pot` (files are found with a recursive `find` command, which means that any package with a `debian/po/templates.pot` file will have it included in the master files as soon as the package sits in `packages/`;

- update `packages/po/*.po` files according to this `template.pot` file

- update all individual packages `debian/po/*.po` files with the translations from these single `packages/po/*.po` files

As a consequence of this process, changes made directly to `debian/po/*.po` files are lost in this process. So, if for some reason, maintainers need to update these files (there is normally no reason for this), they should consider modifying the source files in `packages/po`.

It is however highly recommended that such changes are discussed with &i18n-coords;.

## Handling modifications to templates

### Regular modifications

When maintainers modify the strings in the templates files, the translations will generally need updates. The only exception are typo or spelling corrections, which will be here called "trivial" modifications.

Trivial modifications can be handled with a special process to avoid updates to the translations. This is detailed in the next section.

For regular modifications, maintainers do not need to run the `debconf-updatepo` utility which updates the `debian/po/templates.pot` file as well as all `debian/po/*.po` files. Such updates will be handled by the synchronization script.

Modifications to templates will change the status of the translations for the modified string: in all PO files, this string will be marked as fuzzy. This means that, though the former translation is kept, it is known to be outdated. Fuzzy translations are of course not used: a template which contains at least one fuzzy string will be completely displayed in English. As a consequence, maintainers should not worry about outdated translations, this is the translators job.

This fuzzy string will be marked fuzzy in the general PO files when the synchronization script will be run.

When modifications change the string too deeply, the translations are not kept and thus the string becomes untranslated. The old translation is moved as an obsoleted entry and thus not completely lost.

### Review changes to existing templates

Some peer review is strongly suggested when changing existing debconf templates and the changes are significant enough to motivate a peer review (maintainers should be aware that even minor changes might be inconsistent with the &d-i; writing style, so in doubt, any change should be considered as significant enough).

In such case, it is recommended to first duplicate the existing template, with another name (for instance, the former name followed by _save.

The changed template is then unmarked for translation (by removing the leading "_" character) and a review may be requested in the mailing list.

As soon as the review is completed, the modified template should be marked for translation again.

Before removing the old template, the i18n synchronisation script must be run once to fill in the new template with the former translation, by fuzzy matching.

### Trivial modifications

Trivial modifications are all modifications which have no impact on the translations: these will be most often spelling errors or typos in original templates files.

If the update is made without care, correcting a typo in one template will result in one more fuzzy string in all translations.

In such case, a special unfuzzy process may be run on PO files.

As an example, let's assume that an original template contained the following wrong English sentence:

    These changes will be applied to all partitons.

If the package maintainer simply changes partitons to the correct partitions word, all translations of the paragraph containing this sentence will be fuzzied.

In this case, preventive unfuzzyfication may be done:

    cd <di_dir>/packages/po/
    svn update
    mkdir NEW
    for i in *.po; do
     msgcat --no-wrap $i |\
       sed -e '/^msgid/s/partitons/partitions/g' |\
       msgcat - > NEW/$i && mv NEW/$i $i
    done
    svn commit -m"Preventive unfuzzy before correcting typo in <mypackage>" *.po
    rmdir NEW

Then, the maintainer must immediately correct the typo in the original `<package>.templates` file.

This is a dangerous action. The replacement string in the `sed` command above must be carefully chosen so that it matches only the occurrence that is changed.

The `po4a` package maintainers have written a special tool named `msguntypot` to handle suchpreventive unfuzzyfication. This utility will soon (at the moment of this writing) be included in the `po4a` package as it needs some of its Perl modules. In the meantime, maintainers may ask for it to the &i18n-coords;.

If in doubt, maintainers should contact the &i18n-coords; before committing the error correction to the original templates file.

## String freezes

String freezes are special periods in the &d-i; development process. They are more detailed in string-freezes.

In short, during the release process of &d-i;, the release manager will call for string freezes. A string freeze theoretically forbids any change to templates files in &d-i; packages. It is meant for translators to complete their work without having it outdated by maintainers changes.

Of course, some urgent or critical changes may be needed even during a string freeze. Maintainers needing to commit such changes should first warn the &d-i; release manager and the &i18n-coords; and get their approval before committing.

The &i18n-coords; will warn translators about the unplanned change and will request them for a special update.

Always remember that &d-i; translation is the work of several dozens of teams and thus each change adds more time for all of them to get synchronized again.

## Releasing packages

When releasing their packages, maintainers should use the `scripts/l10n/output-l10n-changes -d .` command. This script will output the changelog entries which should be added to the package's `changelog` file, for translations which got modifications since the last release of the package. This will work properly only if the last changelog entry includes "UNRELEASED".

After running the script, these lines must be added to the package's `changelog` file and process with other release tasks (which are out of scope for this document).