1.4. Internationalising, translating and being internationalised and translated

Debian supports an ever-increasing number of languages. Even if you are a native English speaker and do not speak any other language, it is part of your duty as a maintainer to be aware of issues of internationalisation. Internationalisation is the bridge between you and most of your potential users. Therefore, even if you yourself can function effectively in English, this chapter gives you information you need as a maintainer.

Like the overall i18n implementation, which still has to coalesce into a standard process, l10n within Debian does not yet have a central infrastructure which could be compared to the dbuild mechanism for porting. Currently, most of the work has to be done manually.

1.4.1. How are translations managed within Debian?

Handling translation of the texts contained in a package is still a manual task, and the process depends on the kind of text you want to see translated.

For program messages, the gettext infrastructure is in common usage. For applications the translation is handled upstream, within projects like the Translation Project, the Gnome Translation Project or the KDE Translation Project. The only centralised l10n resource within Debian is the overall Debian translation statistics, where you can find information about the translation status of files found in an actual package. This is similar to Fedora's Translation Status page, but unfortunately different, at this stage, in that we don't yet have a common (unlike it) there is no common infrastructure to facilitate the translation process.

An effort to translate the package descriptions started quite some time ago, even though very few tools currently support these translated descriptions (i.e. only APT can use them, when configured correctly). Maintainers do not need to do anything for this to work, and the translators should use the DDTP. For more information see Section 2.2.2.

For debconf templates, maintainers should use the po-debconf package to help translators work more effectively. Some statistics of the integration of debconf translations in packages can be found on the overall Debian translation statistics pages. For more information, see Section 2.2.1.1

For web pages, each l10n team has access to the appropiate CVS, and the statistics are available at the overall Debian translation statistics site. For more information see Section 2.1.

For general documentation about Debian, the process is more or less the same as for the web pages (the translators typically need access to the CVS or SVN repository holding the documentation files), but there is no statistics pages yet, except for a few specific projects. Central information is definitely needed. For more information see Section 2.4.

For package-specific documentation (man pages, info documents, and information in other formats, like XML/Docbook, HTML and PDF), almost everything has yet to be done. The KDE and GNOME projects handles translation of their documentation in the same way as their program messages, but there is no specific way to handle translation of documentation in Debian project-wide[1]. The translation of Debian-specific man pages was initially handled within the manpages module of the DDP CVS repository, but in some packages, manpages are handled just like generic documentation. For more information on how manpages translations are handled, see Section 2.4.2.

1.4.2. I18N & L10N FAQ for maintainers

This is a list of issues that Debian package maintainers may face concerning I18n and L10n. While reading this, keep in mind that there is not yet any real consensus on those points within Debian, and that they are simply helpful advice. If you have a better solution to a given issue, or if you disagree on some points, feel free to provide your feedback, so that this document can be enhanced.

How do I get a given text translated?

For translate package description or debconf templates, you have do not need to do anything at all. The DDTP infrastructure will send the translatable descriptions volunteers, and process the resulting translations with no need for you to interact. Addition of debconf templates is followed by translation teams that will send you new translations for them through the Bug Tracking System (you can contact debian-i18n, however, if you would like translations before releasing a new package version).

For all other material (PO files for applications, man pages or other documentation), the best solution is to make your text available somewhere on the Internet, and ask the translators on the debian-i18n mailing list to translate your file(s) into their different languages. The translation team leaders, at least, are subscribed to this list, and they will take care of the translation and of the quality-assurance processes. Once this is complete, your translated material will be emailed to you. You may receive queries about context for specific points (inserting context in your document will always ensure a better quality of translation), and get typo reports as a bonus feature.

How do I get a given translation reviewed?

From time to time, somebody might translate some texts included in your package and will ask you to include it when you release. Understandably, you want to know if this translation is up to standard. You don't want to be releasing a campaign speech or a dirty limerick instead. Therefore, you can send the document to the Debian l10n mailing list for that language, asking for a review. Once that is complete, you can feel more confident in the quality of that translation, and can include it in your package with pride. You may also have introduced a new translator to that language team: a valuable resource for Debian.

How do I get a given translation updated?

If you already have some translations of a given text, each time you update the original, you should also politely ask the previous translator to update his/her work, to bring that translation up to date with regard to the current original text. Keep in mind that this task takes time, just as it took you time to update the original: allow for at least one week to get your translation updated, reviewed and returned.

If the translator doesn't respond for some reason, please contact the Debian l10n mailling list for that language. The team-leader should respond promptly. If you don't hear back from the team, please email the Debian i18n mailing list, so it can follow this up or provide alternate contacts for the team. If, somehow, the translation doesn't get done in time (and this is rare, when you follow these procedures), don't forget to put a warning [2] in the translated document, stating that the translation is outdated, so the reader should also refer to the original document if possible.

You should avoid removing a translation completely, simply because it is outdated. An old document is usually better than no document at all for many users. Old translations might also include glossary information that might be useful for future reviews and you never know when a new translator will use the old translation to provide an updated translation (which is typically faster than writting a new translation from scratch).

How do I handle a bug report concerning a translation?

These reports should really go to the translation team, whose contact details are shown in all PO file headers, and should be shown on all documentation. It's a good idea to advise users to send any i18n bug reports straight to language teams[3]. When you do get them, please mark the bug as "forwarded to upstream", and forward it both to the previous translator and to his/her language team (using the corresponding debian-l10n-XXX mailing list).

How can I (as a maintainer) help the translation effort?

You can eliminate a lot of wasted effort, and confusion, by organizing your end of the l10n process. Choose carefully what you want to translate (Debconf messages are always translated, but you might want to have additional items translated), and integrate translation with your release schedule (of either packages or new upstream versions). Allow for a string freeze before a release or package upload: this gives translators time to complete and review translations. Plan to request translations on the debian-i18n mailing list, at a realistic point before release, then again when you announce the string freeze. Communicate readily with debian-i18n and your translation teams: keep the information flowing.

If you are the maintainer of a popular package which might get translations after a release, you might get updated translations for upstream content (program messages and documentation) as bug reports or see changes in upstream's revision control system after you have uploaded a new version. Instead of sitting on the translations waiting for upstream to add them and making a release, you can make this translations available in the Debian package inmediately. This ensures that Debian users will see the translations as soon as they are available and it also boosts the morale of translators which see that their work is made available to users. Translators might get frustated if they send you updated translations for a package (even after sending them to upstream or updated upstream's repository) and do not see them being included in the Debian package until upstream decides to make a new upstream release. Unlike patches for source code, which might introduce regressions and instability, changes to PO files or new translated manpages do not affect the program itself and can be safely added.

1.4.3. I18N & L10N FAQ for translators

While reading this, please keep in mind that there is no general procedure within Debian concerning those points, yet, and that in any case, the most effective way to resolve any issue is to work with your language teams. Language teams are set up to ensure an integrated approach to translation for that language, and that integration includes interfacing with developers.

How can I help the translation effort?

If you are able to join the translation effort, welcome! We appreciate your effort. As a quick guide: decide what you want to translate, make sure that nobody is already working on it (using your debian-l10n-XXX mailing list), translate it, get it reviewed by other native speaker on your l10n mailing list, and provide it to the maintainer of the package (see next point). The Debian i18n web pages, especially the Translation HowTo, can give you more information.

How can I provide a translation for inclusion in a package?

Most importantly, make sure that your translation is correct (by asking for review on your l10n mailing list) before providing it for inclusion. It will save time for everyone, and avoid the chaos resulting in having several versions of the same document in different bug reports. Translation teams are capable of quality work, and that is the reputation we want for Debian i18n.

The recommended way to submit translations is to file a regular bug against the package, with the translation file attached. Make sure to use the 'PATCH' tag, and to not use a gravity higher than 'wishlist', since lack of translations doesn't actually prevent a program from running[4]. For more information please read Section 4.6.

1.4.4. Best current practice concerning l10n

Notes

[1]

The Translation Project and GNU are curently running a pilot project on the manpage translation (and distribution) process which we may be able to implement.

[2]

If the translation is managed through gettext you do not need to do this as the gettext tools will prevent the user from seeing translations that have not been updated.

[3]

Upstream users can add a link on their site, to the Debian language teams listing to prevent getting these mails

[4]

It might, however, prevent people from using it