Localization API

Drupal makes it easy to develop translatable interfaces by offering a few simple functions for writing a module's interface text, and then pushing the rest of the work onto the shoulders of a translator. Additionally, to simplify code patterns for developers, translation magically happens in some cases. Let's discuss the basics of how Drupal translates the interface before diving into the details.

Introduction to interface translation in Drupal

A basic rule is that Drupal assumes that you write modules and themes in English. While technically there is nothing that prevents you from writing a module in Turkish or Chinese, the assumption of English as a default language creates a common ground both for translation and for sharing with the community. All modules and themes are translated from English to other languages.

Drupal finds strings to translate via functions, or "strategic placement" of strings. The most well known function for interface translation is t(). If, for example, you see the following module or theme source code, then you have encountered a string made available for translation.

You should wrap your translatable strings in calls to functions discussed here or place them at well-known locations so that they become translatable. Read on for the specific functions and well-known places. Even though you may miss making some strings available for translation, or you may misuse the functions provided by Drupal, there are tools available that help you check your work.

Short introduction to the translator's view of your module

There are several ways translators find out about your translatable strings. The strings identifiable via the translation functions and found in well-known places could be extracted for translation with the Translation template extractor tool to Gettext Portable Object Template (POT) format, and can be used to create translations in Portable Object (PO) format by either a simple text editor or tailor-made Gettext translation tools.

Drupal itself also collects untranslated strings into the database as it finds them, and tools such as the built-in locale module and the Localization client can be used to translate on the web interface from web page to web page, as you go. Drupal can also export Gettext POT and PO files, and import PO files, making it possible to share translations with others.

Finally, the Localization server is used by many translation teams to collaborate on translation projects. This tool uses the Translation template extractor as a background process to parse multiple modules.

Get the cheat sheet!

Tips and tricks, common pitfalls, relevant functions, important parameters, and placeholder definitions are documented in the Drupal 6 translations cheat sheet (72KB PDF) created by Gábor Hojtsy in November 2007. Although the explanations here provide the necessary context to understand the cheat sheet, it is an invaluable reference for while coding.