tools

Drupal Code Standards: The t() Function

[Note: When we first published this post, we included a work-around for placeholders in Drupal 8. This caught the attention of the Drupal security team and was considered a critical risk, resulting in this issue, and this update. We've removed the section and are happy to have helped bring this issue to light!]

This is the fifth post in a series about coding standards. In this post we’ll talk about how to use translation functions in both Drupal 7 and 8. This is so essential that it deserves its own post!

Other posts in this series:

  1. Drupal Code Standards: What Are They?
  2. Drupal Code Standards: How Do We Implement Them?
  3. Drupal Code Standards: Formatting
  4. Drupal Code Standards: Documentation
  5. Drupal Code Standards: The t() function
  6. Drupal Code Standards: Object Oriented Coding & Drupal 8
  7. Drupal Code Standards: Twig in Drupal 8

What is the t() function?

The t() function allows for localization and translates a given string to a given language at run-time. When coding, you wrap your user-facing strings in this function so that they can be translated.

When do I use it?

In just about every user-facing string. This ensures that your site can be localized! When in doubt, translate everything. You might be thinking "oh, this string will never need to be translated," but 2 years later, when you’re trying to find this string that’s showing up untranslated on the site, and your shareholders want it changed, you’ll be much happier if it’s already ready to translate. I may be speaking from experience here.

What does it do?

Firstly, t() translates text at runtime if you have more than one language enabled. Depending on which placeholder you use, it runs different sanitization functions.

The t() function takes 3 parameters, 2 of which are optional. The first is the string to be translated, the second is the array of replacements, if any. The third is an array of options. From Drupal.org:

$options: An associative array of additional options, with the following elements: * 'langcode' (defaults to the current language): The language code to translate to a language other than what is used to display the page. * 'context' (defaults to the empty context): A string giving the context that the source string belongs to.

String context (or translation context) is a way to organize translations when words have 1 to many translations. From the handbook page:

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.

You can read more about string context here.

Using Placeholders

Placeholders come from the format_string function, which is called by t().

The most common placeholder is probably @variable. This placeholder runs check_plain() on the text before replacing it. Never pass a variable through t() directly - only string literals. The short explanation for this is that the string to be translated needs to be available at runtime, and a variable may not be available and may change its value. You can find an in-depth explanation here.

You use a placeholder to insert a value into the translated text, like in this example from the Advanced Forum contrib module:

$block->title = t(
  'Most active poster in @forum', array([email protected]' => $forum->name)
);

You may also use %variable, which runs drupal_placeholder() on the text, which both escapes the text and formats it as emphasized text.

In Drupal 7, !variable inserts your value exactly as is, without running any sanitization functions, so you would never want to use this on user-entered text, and only on text that has already been properly escaped.

In Drupal 8, !variable is deprecated, as there is no longer a placeholder for unsanitized text.

New in Drupal 8 is :variable, for use specifically with urls.

In Drupal 8, :variable is escaped with \Drupal\Component\Utility\Html::escape() and filtered for dangerous protocols using UrlHelper::stripDangerousProtocols().

When don’t I use it?

In Drupal 7, there are some instances where t() is not available.

During the installation phase, t() isn’t available, so you must use get_t(). You can do something like this:

$t = get_t();
$t(‘my string’);

Translation is also not used inside of hook_schema() or hook_menu().

In Drupal 8, t() is always available, so you can always use it.

t() and links

There are a lot of times that you may want to translate the text in a link - there are lots of ways to do this, and most of them aren’t the best. Here are some bad examples, and a good (and simple!) one.

Bad:


$do_not_do_this = t('Do not ')."<a href="api.drupal.org">" . t('link ') . "</a>"  .t('to something like this.');


$bad = t('This is not a good way to make a @link.', array([email protected]' => '<a href="https://api.drupal.org">'. t('link') .'</a>')); 


$dreadful = t('This is a dreadful way to make a link pointing to the <a href="https://api.drupal.org">Drupal API t() documentation</a>.'); 


$awful = t('This may seem good, but it’s an awful way to link to this @doc.', array([email protected] => l(t(‘documentation'), 'https://api.drupal.org'));

Good:

$good = t('Read about the t() function <a href="@api">here</a>', array([email protected]' => 'https://api.drupal.org'));

Here’s an example from Drupal 8 Core, in the function install_check_translations() in install.core.inc:

// If the translations directory is not readable, throw an error.
    if (!$readable) {
      $requirements['translations directory readable'] = array(
        'title'       => t('Translations directory'),
        'value'       => t('The translations directory is not readable.'),
        'severity'    => REQUIREMENT_ERROR,
        'description' => t('The installer requires read permissions to %translations_directory at all times. The <a href=":handbook_url">webhosting issues</a> documentation section offers help on this and other topics.', array('%translations_directory' => $translations_directory, ':handbook_url' => 'https://www.drupal.org/server-permissions')),
      );
    }

In this code you can see that the <a href> tags are inside the t() function, and the url is escaped using the :variable placeholder.

It’s okay to put a little html in your t() function to simplify like this. The element can easily be moved around if the translation requires it, without needing to know any code other than which word is being linked. Our next section will talk more about keeping your text translatable.

Translation Best Practices

Writing your code and content to be translatable isn’t just a best practice, it may very well be used to actually translate your site, so sometimes you need to think from the point of view of a translator. Try not to abstract out pieces of content too much. Here’s an example. In English, you may have a blog title "Bob’s Homepage." You could want to abstract that into the following:


$username . "‘s " . t(‘Homepage.’);

What’s the problem here? In other languages, this phrase may be re-arranged. For example, in French or Spanish, it would be "Homepage de Bob." The above example would require a translator to change code. We don’t want that. So we write this:

t([email protected] Homepage.’, array([email protected] => ‘Bob’));

Now, this string can easily be changed to:

t(‘Homepage de @user.’, array([email protected] => ‘Bob’));

Concatenation Dos and Don’ts

In the example in the previous section, we showed where concatenating a translated string with another string can make trouble. There are some other things you want to avoid.

Don’t concatenate strings within t(). For example, don’t do this:


t(‘Don’t try to join’ . ‘ ‘ . @num . ‘ ‘ . ‘strings.’, array([email protected] => ‘multiple’));

Even if you think you have to, there is a better way.

And don’t concatenate t() strings and variables - you don’t need to!

Don’t do this:


t(‘This is a complicated way to join ’) . $mystring . t(‘ and translated strings’);

Additionally, the above would give you a codesniffer error because you should not have leading or trailing whitespace in a translatable string.

Do this:

t(‘This is a simple way to join @mystring and translated strings’, array([email protected] => ‘whatever my string is’));

This is how the t() function is designed to be used! Going around it defeats the purpose of using it at all.

Drupal 8 & Twig

In Drupal 8, the essential function and its use are the same. Wrap text in your module code in t(‘’), with the same optional placeholder and options arrays. As noted in the placeholders section, !variable has been deprecated and replaced with :variable.

With Drupal 8, we have the introduction of the Twig templating engine, and with that, new ways format our text for translation.

The simplest way is to pipe your text through |t. Here’s an example from the Devel contrib module:

<thead>
 <tr>
    <th>{{ 'Name'|t }}</th>
    <th>{{ 'Path'|t }}</th>
    <th>{{ 'Info file'|t }}</th>
  </tr>
</thead>

In the above code, we can see the text in the table headers piped into the translation function, just as it would be passed through t() in Drupal 7. You can also use |trans interchangeably with |t. You can use a {% trans %} block to translate a larger chunk of text or use placeholders. These blocks can also handle logic for plurals. Here’s an example from Drupal 8 Core:

<h3 class="views-ui-view-title" data-drupal-selector="views-table-filter-text-source">{{ view.label }}</h3>
<div class="views-ui-view-displays">
  {% if displays %}
    {% trans %}
      Display
    {% plural displays %}
      Displays
    {% endtrans %}:
    <em>{{ displays|safe_join(', ') }}</em>
  {% else %}
    {{ 'None'|t }}
  {% endif %}
</div>

Here we can see that the template appropriately shows the translated text for “Display” or the plural, “Displays.”

From Drupal.org:

Values are escaped by default. The 'passthrough' filter can be used to skip escaping. The 'placeholder' filter can be used to form a placeholder. The default behavior is equivalent to @ in t(), while 'passthrough' matches ! and 'placeholder' matches %.

This comes from Twig, and is not yet commonly used in Drupal, but its usage with placeholders is similar to t(). Here’s an example from Drupal 8 Core:

 {% set includes = includes|join(', ') %}
  {% if disabled %}
    {{ 'Includes:'|t }}
    <ul>
      <li>
        {% trans %}
          Enabled: {{ includes|placeholder }}
        {% endtrans %}
      </li>
      <li>
        {% set disabled = disabled|join(', ') %}
        {% trans %}
          Disabled: {{ disabled|placeholder }}
        {% endtrans %}
      </li>
    </ul>
  {% else %}
    {% trans %}
      Includes: {{ includes|placeholder }}
    {% endtrans %}
  {% endif %}
</div>

In the above code, we can see the use of the placeholder in Twig. The set lines set the placeholders to be used later in the code. The |placeholder filter indicates that a replacement is to be made.

Wrapping Up

This post has a lot of what not to do, but you’ll run into a lot of creatively incorrect code when it comes to translation, and now you’ll know it when you see it. Simple is best. Remember that this function exists to give translators a list of strings to translate, and you’ll be in the right frame of mind when assembling these strings to keep them flexible and translatable!

Have some questions/comments/concerns? Experience you’d like to share? Talk to us on Twitter: @ChromaticHQ!

Keep an eye out for our next post in our Drupal Code Standards series, on Object Oriented programming in Drupal 8!

Drupal Drupal 8 Drupal 7 Code Standards
Alanna Burke Headshot

Alanna's love of content management systems started with Wordpress while working at Temple University, and continued with Drupal at Saint Joseph’s University, then on to Chromatic.