So far I’ve been handling some translations in WordPress and tried to read the official gettext documentation but won’t get the point of one maybe simple thing: What’s the differences between those startings like __(, _e(, etc.? And even more: which others are there beside? Thanks in advance!
Frank
__
(double underscore) is the base translate function. It translates a string and returns it as a string._e
does the same as__
, but echo’s the result immediately._x
is the contextual translate function. It has a second option to provide context to people doing the translation._ex
is the same as_x
, but echo’s the result.Example of using
_x
:Sometimes the same string can be different in other languages. Providing context to the translators can help them pick the right words.
Shortcut functions:
esc_attr__
: Equivalent to__
but also runs the result throughesc_attr
.esc_html__
: Equivalent to__
but also runs the result throughesc_html
.esc_attr_e
: Equivalent to_e
but also runs the result throughesc_attr
.esc_html_e
: Equivalent to_e
but also runs the result throughesc_html
.esc_attr_x
: Equivalent to_x
but also runs the result throughesc_attr
.esc_html_x
: Equivalent to_x
but also runs the result throughesc_html
._n
is the pluralization handler. Example:In that example, there’s two ways to say the number of tacos, depending on if it’s singular or not. The first use of $number tells the
_n
function which version to use. The second use of $number happens in the sprintf, to replace the %d with the actual number in the string.There is no echo function equivalent for
_n
, but there is a function named_nx
. It’s a combination of_n
and_x
. Pluralization and context._n_noop
is a special one. It’s used for translating pluralized strings, but not actually performing the translation immediately. This is useful if you want to make the strings centralized but actually do the work elsewhere. The function that actually does the work elsewhere istranslate_nooped_plural
.Example:
This isn’t used much, but can be handy for organization. If you put all your strings in one file, for example, then reference them elsewhere, this wouldn’t be possible with just
_n
, you need something like_n_noop
to do that._nx_noop
is the same as_n_noop
, but also can take a context for the translators, same as_x
.Note that you can put the domain into either the noop function call, or into the translate_nooped_plural function call. Whichever makes more sense for your organization. If both have a domain, then the one passed to the noop call wins.
number_format_i18n
is the equivalent to PHP’s built-in number_format, but it adds in the handling for things like decimals and so on, which are different in other locales.date_i18n
is the equivalent to PHP’s built-in date, with all the pertinent handling there as well. Month names, day names, etc.Also, never break the laws. Just a reminder. 🙂
__(), _e() and _x(), _ex()
__()
and_e()
are essentially both a wrapper oftranslate()
(do not use directly) and almost the same.The difference lies in that
__()
returns the translated string and_e()
echoes it. Both need to be fed a string as a required parameter and usually, though optional, also a textdomain.Analogously, there’s
_x()
and_ex()
, which let you specify a context that can describe where the string appears. If your project includes more than a few tens of translatable strings, using context makes a lot of sense.Also, note the existence of
_n()
and_nx()
for plurals.Example of common usage
Parameters
All parameters but
$number
are strings.All but
$domain
are required.Further flexibility with variables and sprintf()
If your strings will contain variable numbers or words, use
sprintf()
:Additional resources
Some additional resources for the upcoming WordPress I18n Ninja:
I’m not an expert on translations, but the WordPress Codex Page has good documentation and explains the reason to use each instance.
From the codex pages:
__()
Is used when the message is passed as an argument to another function;
_e()
is used to write the message directly to the page. More detail on these two functions:__('message')
Searches the localization module for the translation of ‘message’, and passes the translation to the PHP return statement. If no translation is found for ‘message’, it just returns ‘message’.
_e('message')
Searches the localization module for the translation of ‘message’, and passes the translation to the PHP echo statement. If no translation is found for ‘message’, it just echoes ‘message’.
Note that if you are internationalizing a Theme or Plugin, you should use a
"Text Domain"
.The gettext framework takes care of most of WordPress. However, there are a few places in the WordPress distribution where gettext cannot be used:
Link to the Codex Page
Additional info regarding when gettext doesn’t work
Hopefully that answers your question, if not let us know and maybe someone else can help or I can do some more research.