Note: This handbook page is under discussion, see #1035716: [policy, no patch] Decide and document guidelines for using string context
What is string context?
When translating Drupal’s user interface to other languages, each original (English) string can have only one translation. This is a problem when one English word has several meanings, like "Order", which can mean the order of elements in a list, to order something in a shop, or an order someone has placed in a shop. For many languages, the string "Order" needs a different translation for each of these meanings.
In Drupal 7.x and later, it is possible to make different versions of such strings for translation. This is done by adding text to make unique strings for each meaning. This extra text is called string context. ("Translation context" is also used.) It can also give useful information to the translators. It’s not shown to the end user, so for English versions of Drupal there’s no visible difference.
How to add context for a string
Example, adding the context “Number of digits” to the string “Scale”:
- '#title' => t('Scale'),
+ '#title' => t('Scale', array(), array('context' => 'Number of digits')),
When you add a context, all existing translations for that string are broken and must be added anew, so make sure you only add contexts when needed.
If core or other modules have contexts covering the same use cases, reuse them instead of creating your own.
Guidelines for choosing text for the contexts
Write a short description of how the string is used. If possible, avoid mentioning which module it’s used in. (This makes it easier to reuse the context in other modules.)
You can include spaces and capital letters in the text.
List of contexts used
You can find all contexts at http://localize.drupal.org/translate/languages/test/translate. Note that this shows all contexts which have been used in all released versions of projects. If a context is removed or changed in a later version (ie. because of a typo, or because it was found not to be needed), it will still show up in this list.
To see where a specific context is used, filter for the context, and then click on the link “Show related projects”.
There is an open issue for making a better list of string contexts at #1034882: Make list of contexts used more evident for developers
How to request a new context
Open issues for the relevant projects, ask for context to be added.
Link to this handbook page, and use the issue tag string context to make it easier to find related issues in the future.