wppaste
WordPress

_x( string $text, string $context, string $domain = 'default' ): string

Since
2.8.0
Source
wp-includes/l10n.php:409

Disambiguates a translatable string by pairing $text with $context before looking it up in the $domain text domain, so translators can give the same English word different renderings depending on where it appears. Plugins and themes should always pass their own text domain, since the default 'default' domain is reserved for WordPress core strings. If no matching translation exists for that text, context, and domain combination, _x() simply returns $text unchanged, so an untranslated site or missing .mo/.po file will not reveal any bugs in how the context is set up.

Retrieves translated string with gettext context.

Description

Quite a few times, there will be collisions with similar translatable text found in more than two places, but with different translated context.

By including the context in the pot file, translators can translate the two strings differently.

Compatibility

WordPress
since 2.8.0
PHP
7.4–8.6-dev
  • 6.7.7
  • 6.8.8
  • 6.9.7
  • 7.0.4
  • 7.1.0

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$textstring
Text to translate.
$contextstring
Context information for the translators.
$domainstringoptional
Text domain. Unique identifier for retrieving translated strings.
Default 'default'.Default: 'default'

Return value

string
Translated context string without pipe.

Code examples

Every example is editable and runs in a real WordPress booted in your browser by WordPress Playground. Press Run, then edit the code: clicking away re-runs it. Nothing is sent anywhere until you do.

Add gettext context to a reused admin label like a column header

A word like "Comments" needs different translations depending on whether it labels a table column or a menu item, so pass a context string alongside it.

$column_label = _x( 'Comments', 'column name', 'default' );
$menu_label   = _x( 'Comments', 'admin menu', 'default' );

echo esc_html( $column_label ) . "\n";
echo esc_html( $menu_label );

On a site running in English with no translation loaded, both calls print the plain word "Comments" because _x() falls back to $text when no matching translated string is found.

Disambiguate a plugin field label from an unrelated use of the same word

A plugin displays the price stored as post meta on post 2, and needs the label "Price" to translate differently from a verb like "to price" something.

$price_label = _x( 'Price', 'product field label', 'my-plugin' );
$price       = get_post_meta( 2, 'price', true );

printf(
	'%s: %s',
	esc_html( $price_label ),
	esc_html( $price )
);

The text domain 'my-plugin' must match the domain registered when the plugin loads its translation files, or the string will never pick up a translation even if one exists.

Common problems and fixes · 3

Why does _x() just return the exact string I passed in?

translate_with_gettext_context() only returns a translated string when a .mo or .po file for the given $domain contains an entry matching both $text and $context. On an English-locale site, or one without that translation file loaded, there is nothing to match, so the function falls back to returning $text unchanged.

Should I use __() or _x() for a string like 'Post'?

__() has no context parameter, so two identical source strings used in different situations (a noun like 'Post' the object versus a verb like 'Post' the action) collide in the .pot file and translators cannot tell them apart. _x() exists specifically to add that missing disambiguation.

Why doesn't the context I pass show up anywhere in the output?

The return value is documented as the 'translated context string without pipe', meaning $context is only used internally as a lookup key alongside $text and is never appended to or shown in the returned text.

Alternatives and related functions

__
When the string is unambiguous on its own and does not collide with an identical string used in a different situation.
_ex
When you need the same context-aware lookup but want the result echoed immediately instead of returned.
_nx
When the string also needs plural forms in addition to disambiguating context.
esc_html_x
When the translated, context-aware string is being printed directly into HTML and needs escaping at the same time.

Performance profile

How much work a call to _x() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class
Trivial

Touches nothing outside its own arguments.

Scaling
Constant

No loop in the body: the same number of instructions runs whatever you pass in.

Instructions
9

Executed per call on PHP 8.5. The body compiles to 9.

Plugin surface
None

Nothing here hands control to plugin code.

Called by
50

50 places in core call this, so the cost is paid more often than your own code shows.

What it touches

  • hookthird-party callbacksapply_filters()one call below _x()

Further down the call graph this can also reach query, option, cache, serialize and transient. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 1 distinct outcome

One number would be a lie: the work depends on which branch runs. These are every distinct cost _x() can have, taken from its control-flow graph on PHP 8.5.

WhenInstructionsCalls it makes
always9translate_with_gettext_context()

Across PHP versions

Compiles the same on PHP 7.4, 8.1, 8.2, 8.3, 8.4, 8.5 and 8.6-dev: 9 instructions, 9 executed per call, 0 branches. The work does not change between versions.

An instruction is not a fixed amount of time, so a matching count is not necessarily the same speed; what it rules out is a difference in the work itself.

Uses · 1

Used by · 50

Show all 50

Source code

View on Trac View on GitHub 

function _x( $text, $context, $domain = 'default' ) {	return translate_with_gettext_context( $text, $context, $domain );}

Changelog

Introduced in 2.8.0. Unchanged from 6.7.7 through 7.1.0.

  1. 6.7.7
  2. 6.8.8
  3. 6.9.7
  4. 7.0.4
  5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data
Generated from the wordpress-develop 7.1.0 tag, from src/wp-includes/l10n.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.
Corrections
Something wrong on this page? Report it and it gets fixed in the next regeneration.