Developers need the whole source tree, which requires the use of git and mr: git clone git@salsa.debian.org:installer-team/d-i.git cd d-i ./scripts/git-setup mr checkout In the past, we had everything in one subversion repository. Then one day, the developer parts were migrated to git, while the translator files were left on subversion; this is why we had the project divided into two parts now. Then, the Alioth server was replaced by Salsa, and thus everything was migrated to git. 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 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. &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 on 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, even 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. Maintainers must respect the Debconf Templates Style Guide (DTSG) (see the section General recommendations for authors and translators of the Debian Developers Reference). In any case, before committing new templates or templates changes, these templates must have been reviewed by other &d-i; developers or an internationalisation (i18n) coordinator. 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. Packages which are newly added to &d-i; can ignore this. Their templates may be marked as translatable, because these packages are ignored by the synchronisation script until they are added to the packages/po/packages_list file (see ). After adding the new templates or the new package, maintainers must request for peer review on &email-debian-boot-list;. New packages will be added to the master files only when this review has been completed. Strings which need translation must be prepended by a leading underscore (_) character in the templates file after the strings review: Template: debian-installer/foo/bar Type: note _Description: New note This is a completely new note, added for package foo. Then, the synchronisation script will automatically add the two new strings to the translators files, allowing them to work on translations. 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 packages listed in packages/po/packages_list are merged into five po files per language and translators just work on these files. These so-called master PO files are kept in packages/po/sublevelX in the &d-i; main directory. These files are the only files edited by translators. All other PO files as well as PO "templates" files (POT files) are automatically generated by the synchronization script (see ): merge all templates.pot files into packages/po/template.pot (included are all debian/po/templates.pot files for packages listed in packages/po/packages_list); update packages/po/sublevelX/*.po files according to this template.pot file; update all individual packages debian/po/*.po files with the translations from these single packages/po/sublevelX/*.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/sublevelX/. It is however highly recommended that such changes are discussed with &i18n-coords; (or handed over to them). 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. 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 l10n-sync script must be run once to fill in the new template with the former translation, by fuzzy matching. 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/ git pull 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 git add * git 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 such preventive unfuzzyfication. If in doubt, maintainers should contact the &i18n-coords; before committing the error correction to the original templates file. String freezes are special periods in the &d-i; development process. They are more detailed in . 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. 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).