Internationalization is the process of enabling your theme to be translated into different languages. We require that all themes be fully internationalized so that they can be enjoyed by the largest audience possible. In this document we will look at the basics of how to prepare your theme for translation as well as explain common errors.
Take for example the following sentence: “The quick brown fox jumps over the lazy dog”. To prepare this for translation and echo it to the screen, we can use the WordPress core function
_e(). This function accepts two parameters, the first is the text to be translated and the second is a textdomain unique to your theme. Here’s an example:
<?php _e( 'The quick brown fox jumps over the lazy dog', 'mytheme' ); ?>
As a best practice, it is important to minimize or completely remove the amount of HTML code that appears in internationalized strings. For example the following code:
<p>The quick brown fox jumps over the lazy dog.</p>
One way of enabling this text to be translated is to use the
<?php _e( '<p>The quick brown fox jumps over the lazy dog.</p>' ); ?>
While this code functions perfectly fine, it is not the best approach. There is no need to add the paragraph tags to the string. A better approach to this situation is to move the paragraph tags outside of the
_e() function. We do this because there is no need to translate this markup and it is easy to move it.
<p><?php _e( 'The quick brown fox jumps over the lazy dog.' ); ?></p>
There are times when markup is better left inside the string. If we need to emphasize the phrase “jumps over” in the sentence above we would end up with the following code:
<p><?php _e( 'The quick brown fox <em>jumps over</em> the lazy dog.' ); ?></p>
In this case it is not so easy to remove the tags. If we were to do this 3 sentence fragments would be created:
- The quick brown fox
- <em>jumps over</em>
- the lazy dog.
Perserving the sentence as a whole is more important than removing the markup from the translated string.
If we need to internationalize a sentence that incorporates the value of a variable or the return value of a function, we can utilize
sprintf(). These functions are very similar, the difference being that
printf() will echo the text to the screen while
sprintf() returns the value.
What would happen if our theme had a feature that allowed users to choose which animal gets to jump over the dog? Perhaps it provides a function to get the user-defined value called
mytheme_get_jumping_animal(). Our theme needs to display this value inside the sentence while still allowing sentence to be translated. The following example will not work because functions cannot be included in internationalized strings.
<p><?php _e( 'The quick brown ' . mytheme_get_jumping_animal() . ' jumps over the lazy dog.' ); ?></p>
We need to move the function outside of the string. This is pretty easy to do utilizing
printf(). Here’s what the finished code looks like:
<p><?php printf( __( 'The quick brown %1$s jumps over the lazy dog.' ), mytheme_get_jumping_animal() ); ?></p>
Here we have replaced
__() which allows the string to be returned instead to echoed to the screen. Next we pass the return value of
__() as the first parameter to
printf(). Then we pass the return value of
mytheme_get_jumping_animal() as the second parameter. Finaly, we add a placeholder to the translated string where
mytheme_get_jumping_animal() used to be. Let’s take a look at how this works:
- A person will translate the string “The quick brown %1$s jumps over the lazy dog.” All words will be translated into the second language and the placeholder will be moved to the appropriate place in the sentence.
__()will return the translated string.
%1$swith the return value of
printf()will echo the finished sentence to the screen.
Escaping Text Strings in Attributes
All strings must be escaped with
esc_attr_e() before they are used as HTML attributes. The escaping must be done as late as possible. Here is the best way to escape a simple string used as the title attribute of an anchor:
<a title="<?php esc_attr_e( 'The quick brown fox jumps over the lazy dog', 'mytheme' ); ?>">
Here’s a more complex example with a dynamic value and a placeholder:
<a title="<?php echo esc_attr( sprintf( __( 'The quick brown %1$s jumps over the lazy dog.' ), mytheme_get_jumping_animal() ) ); ?>">
Escaping HTML Strings with Dynamic Attributes
In cases where html is included inside the string and dynamic values are used for the value of an attribute, these values must be escaped immediately before they are sent as parameters to
printf(). Here’s an example where a link is included in the translated string and the URL is provided by a function:
<?php printf( __( 'The quick <a href="%1$s">brown fox</a> jumps over the lazy dog.' ), esc_url( mytheme_get_fox_url() ) ); ?>
The following examples illustrate situations where internationalization is commonly use incorrectly. While most of these examples will be caught by the WP.com Theme Review checks in the VIP Scanner plugin, it is a good idea to keep an eye out for these while developing.
The following values should not be translated:
__( '', 'mytheme' ); // Empty strings. __( $variable, 'mytheme' ); // Single variables. printf( __( '%s' ), $var ); // Single placeholders __( mytheme_function(), 'mytheme' ); // Single functions
The following dynamic values can not be sent directly to a gettext function like
Please see the Dynamic Text section for instructions.
__( "Hello there, $name", 'mytheme' ); // variables __( "Hello there, " . mytheme_get_name(), 'mytheme' ); // functions