Using t() for translatable stringsfor Drupal 8 , 9 , 10 , and 11

Introduction

Welcome to another tutorial in our "Module Development" series where we're focusing on ensuring your custom modules are multilingual-ready. Making your strings translatable is an essential aspect of developing a flexible and versatile Drupal module. Today, we will delve into the t() function, which is a cornerstone of string translation in Drupal.

The Importance of Translatable Strings

In today's globalized digital landscape, websites often cater to audiences speaking multiple languages. Offering a seamless experience across different languages can significantly enhance accessibility and user satisfaction. By making your strings translatable, you prepare your module for diverse audiences, allowing content to be displayed in the user's preferred language.

Understanding the t() Function

The t() function in Drupal is a powerful tool for string translation. It allows you to wrap a string and make it translatable, automatically looking for existing translations for the user’s language preference. Here is a typical syntax for the t() function:

t('Your string here');

By default, t() will look for the string in the base language of your website and require you to provide translations through the interface or via .po files, which we will cover in the next lesson.

Using t() in Your Code

To illustrate how t() is used, let's revisit a previous example where we create a custom block in our module. Below is how you might define a block with translatable strings:

use Drupal\Core\Block\BlockBase;

class MyCustomBlock extends BlockBase {
  public function build() {
    return [
      '#markup' => t('Welcome to My Custom Block!'),
    ];
  }
}

Here, t('Welcome to My Custom Block!') makes the string "Welcome to My Custom Block!" translatable. When translations are provided, Drupal will display the appropriate language version based on user preferences.

Placeholders and HTML Tags

The t() function can also manage placeholders and HTML tags, ensuring your strings are dynamic and formatted correctly:

t('Hello, @name! Welcome to our site.', [
  '@name' => $user_name,
  '@url' => $welcome_url,
]);

In this example, @name and @url serve as placeholders that will be replaced by actual variable values. Drupal then handles translations of the static parts of the string while inserting the dynamic content safely.

Translating Arrays of Strings

It's not uncommon to have an array of strings that need translation. Drupal provides a helper function for such use cases:

$items = [
  ['#markup' => t('First item')],
  ['#markup' => t('Second item')],
];

This approach is advantageous when each array element must be wrapped for translation individually. Ensure that all string elements in arrays are passed through t() for consistent translations.

When Not to Use t()

It's important to recognize when t() should not be used. Avoid this function for translating data-driven content—such as user-generated content or configuration values. Use it primarily for hardcoded, user-facing strings that need consistent translation across the site interface.

Testing and Debugging Translations

After marking strings for translation, you should test by switching site languages and verifying translations appear correctly. Regularly check the Translations Report in your Drupal admin panel to ensure translations are properly applied.

Conclusion

Implementing the t() function is a crucial step in preparing your Drupal module for a multilingual environment. Remember to wrap all hardcoded, user-facing strings with this function and test across different site languages to ensure a seamless user experience. By doing so, you not only improve accessibility but also broaden your website's reach.

What's Next?

Now that you've grasped using t() for translatable strings, our next lesson will guide you through defining .po files for module translations. This is where you will learn to provide actual translations for your strings, further expanding your site's linguistic capabilities.