Best practices for localization and internationalization
This documentation offers best practices and guidance for localization and internationalization of software, multimedia content and websites.
The content was gathered by localization experts Translate House for open source software and open hardware projects funded by the Next Generation Internet research and development initiative, specifically the NGI Zero PET grant for privacy and trust enhancing technology and NGI Zero Discovery grant for improving search and discovery.
Translate House originates from Translate.org.za, a South-African non-profit that pioneered community localization of widely used open source tools like Firefox and OpenOffice.org into the 11 official South-African languages.
This guide can also help readers generally interested in localization and internationalization of software, multimedia content and websites.
What is localization?
We live in a connected world, there is a proliferation of digital content, software, web apps and mobile apps. The concept of localization is becoming crucial in such a globalized planet. This best practices document will guide you in this process.
Let’s first define some terms that are commonly used.
Localization is adapting computer software, video games, multimedia content and websites for use in a new language. Think of this as the translation of the text and other changes required to make it function properly in a specific language or country. Localization is often referred to as l10n (as in: “L”, followed by ten more letters, and then “N”).
Internationalization is a set of engineering activities to make the software adaptable to other languages and cultures. Internationalization therefore enables localization. It makes the product translatable, but also makes it aware of language and country specific conventions that differ, such as formats for time, date, currency and numbers. Think of internationalization as the project work that will make localization into many languages easy. Internationalization is often referred to as i18n (as in: “I”, followed by eighteen more letters, and then “N”).
This document provides a highly summarized overview of the main concepts and steps to take.
What do I need to do?
Step 1: Prepare your project
• Consult the i18n documentation for your programming language, platform, and/or build system. Some best practices relevant to your situation might be covered there.
• Make the necessary changes to enable a locale — at least implicitly (from the HTTP Accept-Lang header or standard environment variables), but optionally explicitly through user interaction.
• Mark all translatable strings. If GNU Gettext is used, it is common to see translatable strings in the code marked with the function call _(), for example _("Keyboard shortcuts").
• Ideally your code should work perfectly with incomplete translations, not only 100% complete ones. With Gettext this is automatically handled.
If done properly, adding support for a language is now often as easy as simply adding the translation file(s) for that language.
Step 2: Gather source text
• Ensure that all localizable material is together in one place. Depending on the platform, the source text to translate might already be isolated in certain files, or need to be extracted into a template file, for example a Gettext .pot file extracted with xgettext.
• Review the text for quality, such as spelling, consistency, etc.
• If translations are managed in a dedicated system, upload this new version.
• Consider announcing a “string freeze” — a period before a release with no string changes so that translators have enough time.
Step 3: Update existing translations
If there are existing translations from a previous version, they need to be updated to the new source material. For Gettext projects, this can be done with msgmerge. This step might be performed automatically by a build system or online translation management tool. Some localizers might be familiar with this step, but rather don’t count on it.
Step 4: Open the process to localizers
• Provide instructions for your localizers on what is expected from them. Note deadlines and any special instructions.
• Developers or localizers might prioritize certain files or sections over others.
• Try not to limit what tools localizers can use — they might have a toolset that they prefer to use. There are dedicated standalone and web-based tool for translation.
• Localizers translate, review and resubmit the work.
Step 5: Integrate translations
• Translations are committed to the version control system, and integrated with the build system if required.
• Update any tests that might be affected, and ensure that the new language builds and works.
Step 6: Testing
• Document how localizers can test localized versions. It is highly beneficial if localizers can easily test their translations without waiting for a new release.
• If required, provide builds with the new contributions for users to test.
Reach out to ideal testers: the users from your target audience in each language. Keep in mind that a localized version could expose bugs in the code!
When updating your software,collaborators might go back to the translation step 3, or the whole process could be repeated as part of the normal software development lifecycle for each version.
General Best Practices
• Get started with localization process during the early stage of development.
• Consider making i18n part of your coding guidelines, and handle relevant issues during code review.
• Always use Unicode for text encoding.
• Allow support for non English input.
• Be careful if you manipulate text. Different languages have different expectations with regards to sorting, capitalization, punctuation, numbers, plurals, etc.
• Where possible, correctly annotate the language, for example with the (xml:)lang=”xx” attribute in HTML/XML.
• Consider common practice with the outside world for localization too, such as Wikipedia, which is highly multilingual. (see further information for links)
• Leave ample space in your user interface elements to allow text expansion which generally occurs when translating from English into other languages.
• Keep right-to-left (RTL) languages in mind. Your platform (Qt, GTK, Web, etc.) should have best practices to support such languages.
• Be aware of cultural differences. Color, icons or graphics represent different meanings in different cultures.
• Avoid text in images, as this makes it harder to perform and manage localizations.
Further Information
Wikipedia on language localization: wikipedia.org/wiki/Language_localisation
Wikipedia on internationalization: wikipedia.org/wiki/Internationalization_and_localization
Coloring and cultural symbolism: translation-blog.multilizer.com/color-localization-infographics GNU Gettext ( internationalization and localization system) manual: gnu.org/software/gettext/manual/
Translate House 