L10N Guidelines for Developers

Introduction

This page aims to help software developers getting familiar with the localization (l10n) tools and the internationalization (i18n) process. The focus is primarily the GNOME project and GNOME software. It should however also serve as a useful source of information for non-related software projects too. It should cover most of the aspects of localization, from the technical details on how to enable localization, to how to avoid common pitfalls and how to prevent making the translation work for translators unnecessarily troublesome.

Why localize?

The process of localization is making software accessible to users of a different language or a different culture. The last part is important. Users may share more or less the same language but still require different settings due to differences in culture and society.

Why should one localize? It's a complex question with many answers, but one is of course that this dramatically helps attract many more users. In the free software world, a large user base is not only important because it helps getting the software tested, but it also helps with getting potential new contributors in the future, in addition to several other important benefits. Another aspect is the aspect of freedom. The user has the freedom to chose whatever localization of your software that he or she prefers and is most comfortable with, thanks to the software supporting localization. Please bear in mind that you as a developer only have to enable localization in the software. Lots of the other hard work is done by other volunteers such as translators and developers of the libraries and tools used. Thus it is usually a small price to pay for the user getting a lot of freedom and an accessible application.

The most well-known aspect of localization is the localization of the language, the translation, but localization also covers a lot of other aspects, ranging from the decimal character used, the thousands separator used, whether the week starts on Sunday or Monday, or whether other icons or symbols are needed, and countless other aspects. Most of these should be considered as important as the translation. The translation is just one of several steps needed for making the software usable to people around the world. If the user should have difficulties understanding for example the display of a decimal number, then the application still isn't accessible. Even if the user does understand it but it is presented in a, from his or her perspective, very strange and inconvenient format, then the application still isn't accessible. Other similar applications that can present the values correctly will most likely be preferred. Worse, the user might even interpret the value wrongly, like for example with different and ambiguous date formats or different decimal and thousands separators, in which case the end result can be disastrous.

Topics and common issues

• Localize using gettext and intltool

• Use some translation project

• Avoid creating multi domain modules

• Use clear, simple and consistent language

• Avoid expanding acronyms

• Avoid using names that require localization

• Avoid images and symbols that require localization

• What should be localized?

• Use comments

• Translation contexts

• Don't mark empty strings for translation

• Use locale-provided values

• Don't use anything besides ASCII or UTF-8 in messages

• Don't use too short messages

• Don't use too long messages

• Avoid hard-coded line breaks

• Never split sentences

• Plurals

• Avoid markup wherever possible

• Make messages generic

• Enclose literal values in double quotes

• Add translator credits

• Values of schema settings, e.g. in dconf/gconf

• Test your internationalization before string freeze

Additional resources

• GNU Gettext Manual

• Internationalization section in Overview of the GNOME Platform document

• GNOME Localization Style Guides - These are actually Sun's Solaris style guides but they should be generic enough to apply to any project (including GNOME)

• MigratingFromIntltoolToGettext

• GnomeI18nDeveloperTips - should be moved to this page

Outdated resources

These documents are now outdated and should be moved to TranslationProject wiki pages.

• Internationalising GNOME applications by Malcolm Tredinnick

• Internationalization in GTK+ by Owen Taylor

CategoryGnomeI18n CategoryDeveloperTutorial