Skip to main content

​
Internationalization (i18n)

The @wordpress/i18n package provides internationalization utilities for client-side localization in WordPress. It allows you to translate text strings in your JavaScript code, similar to how PHP functions work on the server side.

​
Installation

You can install the package using npm: 
npm install @wordpress/i18n --save
This package assumes your code will run in an ES2015+ environment. If you’re targeting environments with limited support for modern JavaScript features, include the polyfill from @wordpress/babel-preset-default.

​
Basic Usage

import { sprintf, _n } from '@wordpress/i18n';

sprintf( _n( '%d hat', '%d hats', 4, 'text-domain' ), 4 );
// Output: "4 hats"
For comprehensive examples, see the Internationalization section of the Block Editor Handbook.

​
Translation Functions

​
__( text, domain )

Retrieves the translation of text.
​
text
string
required
Text to translate.
​
domain
string
Domain to retrieve the translated text.
​
return
string
Translated text.
import { __ } from '@wordpress/i18n';

const greeting = __( 'Hello World', 'my-text-domain' );

​
_x( text, context, domain )

Retrieves translated string with gettext context.
​
text
string
required
Text to translate.
​
context
string
required
Context information for the translators.
​
domain
string
Domain to retrieve the translated text.
​
return
string
Translated context string without pipe.
import { _x } from '@wordpress/i18n';

const readVerb = _x( 'Read', 'verb', 'my-text-domain' );
const readAdjective = _x( 'Read', 'past participle', 'my-text-domain' );

​
_n( single, plural, number, domain )

Translates and retrieves the singular or plural form based on the supplied number.
​
single
string
required
The text to be used if the number is singular.
​
plural
string
required
The text to be used if the number is plural.
​
number
number
required
The number to compare against to use either the singular or plural form.
​
domain
string
Domain to retrieve the translated text.
​
return
string
The translated singular or plural form.
import { _n } from '@wordpress/i18n';

const message = _n(
	'You have one new message',
	'You have %d new messages',
	5,
	'my-text-domain'
);

​
_nx( single, plural, number, context, domain )

Translates and retrieves the singular or plural form based on the supplied number, with gettext context.
​
single
string
required
The text to be used if the number is singular.
​
plural
string
required
The text to be used if the number is plural.
​
number
number
required
The number to compare against to use either the singular or plural form.
​
context
string
required
Context information for the translators.
​
domain
string
Domain to retrieve the translated text.
​
return
string
The translated singular or plural form.

​
String Formatting

​
sprintf( format, …args )

Returns a formatted string. This function is similar to PHP’s sprintf().
​
format
string
required
The format of the string to generate.
​
args
...any
required
Arguments to apply to the format.
​
return
string
The formatted string.
import { sprintf, __ } from '@wordpress/i18n';

const message = sprintf(
	__( 'Hello, %s!', 'my-text-domain' ),
	'World'
);
// Output: "Hello, World!"

​
Locale Management

​
setLocaleData( data, domain )

Merges locale data into the Tannin instance by domain. Accepts data in a Jed-formatted JSON object shape.
​
data
object
Locale data configuration.
​
domain
string
Domain for which configuration applies.
import { setLocaleData } from '@wordpress/i18n';

setLocaleData(
	{
		'': {
			domain: 'my-text-domain',
			lang: 'es',
		},
		'Hello World': [ 'Hola Mundo' ],
	},
	'my-text-domain'
);

​
getLocaleData( domain )

Returns locale data by domain in a Jed-formatted JSON object shape.
​
domain
string
Domain for which to get the data.
​
return
object
Locale data.

​
resetLocaleData( data, domain )

Resets all current Tannin instance locale data and sets the specified locale data for the domain.
​
data
object
Locale data configuration.
​
domain
string
Domain for which configuration applies.

​
Utility Functions

​
hasTranslation( single, context, domain )

Checks if there is a translation for a given string (in singular form).
​
single
string
required
Singular form of the string to look up.
​
context
string
required
Context information for the translators.
​
domain
string
required
Domain to retrieve the translated text.
​
return
boolean
Whether the translation exists or not.

​
isRTL()

Checks if current locale is RTL (Right To Left).
​
return
boolean
Whether locale is RTL.
import { isRTL } from '@wordpress/i18n';

if ( isRTL() ) {
	console.log( 'Current locale is right-to-left' );
}
RTL (Right To Left) is a locale property indicating that text is written from right to left. For example, Hebrew (he) and Arabic (ar) are RTL languages. The opposite, LTR (Left To Right), is used in languages like English (en), Spanish (es), and French (fr).

​
Advanced Features

​
createI18n( initialData, initialDomain, hooks )

Creates an i18n instance for isolated translation contexts.
​
initialData
object
Locale data configuration.
​
initialDomain
string
Domain for which configuration applies.
​
hooks
object
Hooks implementation.
​
return
object
I18n instance.
import { createI18n } from '@wordpress/i18n';

const customI18n = createI18n();
customI18n.__( 'Hello', 'my-domain' );

​
defaultI18n

The default, singleton instance of I18n used by all the top-level translation functions.

​
subscribe( callback )

Subscribes to changes of locale data.
​
callback
function
required
Subscription callback function.
​
return
function
Unsubscribe callback.
import { subscribe } from '@wordpress/i18n';

const unsubscribe = subscribe( () => {
	console.log( 'Locale data changed' );
} );

// Later...
unsubscribe();

​
Version

Current version: 6.13.0

Build docs developers (and LLMs) love

Get started for freeTalk to us