Drupal Translation Placeholder Prefixes

Good documentation can, at times, be so very very hard to find.

Once such piece of elusive documentation is about the prefix for placeholder tokens used in Drupal’s translate t() function.

This function engages Drupal’s ability to translate a string. It is most commonly used while programming hard coded strings within your code. For example: creating a settings form for a custom module.

The signature of this function goes a little something like this…

$t(string: $value_to_be_translated, array: $placeholder_text, array: $options): string

$value_to_be_translated is the string that is going to be translated. Typically, this value is hard coded.

$placeholder_text is the array of placeholder tokens and associated replacement strings that are used within the $value_to_be_translated argument. Its values typically consist of variables that are within the current scope of the code.

$options is an array of options that can contain the langcode of the language in which $value_to_be_translated is written within the code (the hard coded string). It can also contain context of the translation which allows for distinction between identical hard coded strings that may differ upon translation based on their context.

A typical use of this function would look like:

$output = t('Good @time_of_day %name! Here is your <a href=":url">one time access link</a>.',
  [ 
    '@time_of_day' => $time_of_day,
    '%name' => $name,
    ':url' => $access_link,
  ]
);

In order to successfully use the placeholders one must use certain prefixes or otherwise be faced with an error. I must admit that the handling options that Drupal provides is pretty cool, but I find the prefixes difficult to memorize and keep track of.

And herein lies the problem… It doesn’t clearly appear that Drupal.org’s documentation, nor Stack Overflow, nor private blogs, are super keen on documenting this in a way that is easy to find.

Googling this with the following keywords does not yield any helpful results within the first couple of result pages:

  • Drupal t function token prefix
  • Drupal t function placeholder prefix
  • Drupal translate token prefix
  • Drupal translate placeholder prefix
  • Drupal t function token prefixes
  • Drupal t function placeholder prefixes
  • Drupal translate token prefixes
  • Drupal translate placeholder prefixes

The only place where this can be somewhat easily found is in the api.drupal.org documentation though the explanation on this page is a bit dense.

And so, I am writing this here so I don’t loose my mind constantly searching for it.

Prefix Description Input Example Output Example
@

When the replacement value is a string it is sanitized.

When the value is a MarkupInterface object, the replaced value in the returned string is not sanitized.

If the MarkupInterface object is cast to a string it will be sanitized.

 
<strong>Hello World</strong>
 
&lt;strong&gt;Hello World&lt;/strong&gt;
% When the replacement value is a string it is sanitized and wrapped in <em> tags. 
<strong>Hello World</strong>
 
<em class="placeholder">&lt;strong&gt;Hello World&lt;/strong&gt;</em>
: When the replacement value is a string (URL) it is stripped of URL protocols that can be cross site scripting vectors and encodes HTML characters. 
javascript://example.com?q=<a href=test>Hello World</a>
 
//example.com?q=&lt;a href=test&gt;Hello World&lt;/a&gt;
!

When the replacement value is a string, do not sanitize it.

Discontinued as of Drupal 8.

 
<strong>Hello World</strong>
 
<strong>Hello World</strong>

In Drupal 8+ results in an error.
(No Prefix)

When the replacement value is a string, do not sanitize it.

Discontinued as of Drupal 8.

 
<strong>Hello World</strong>
 
<strong>Hello World</strong>

In Drupal 8+ results in an error.

 

Tags