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:
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

Translation Functions

__( text, domain )

Retrieves the translation of text.
string
required
Text to translate.
string
Domain to retrieve the translated text.
string
Translated text.

_x( text, context, domain )

Retrieves translated string with gettext context.
string
required
Text to translate.
string
required
Context information for the translators.
string
Domain to retrieve the translated text.
string
Translated context string without pipe.

_n( single, plural, number, domain )

Translates and retrieves the singular or plural form based on the supplied number.
string
required
The text to be used if the number is singular.
string
required
The text to be used if the number is plural.
number
required
The number to compare against to use either the singular or plural form.
string
Domain to retrieve the translated text.
string
The translated singular or plural form.

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

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

String Formatting

sprintf( format, …args )

Returns a formatted string. This function is similar to PHP’s sprintf().
string
required
The format of the string to generate.
...any
required
Arguments to apply to the format.
string
The formatted string.

Locale Management

setLocaleData( data, domain )

Merges locale data into the Tannin instance by domain. Accepts data in a Jed-formatted JSON object shape.
object
Locale data configuration.
string
Domain for which configuration applies.

getLocaleData( domain )

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

resetLocaleData( data, domain )

Resets all current Tannin instance locale data and sets the specified locale data for the domain.
object
Locale data configuration.
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).
string
required
Singular form of the string to look up.
string
required
Context information for the translators.
string
required
Domain to retrieve the translated text.
boolean
Whether the translation exists or not.

isRTL()

Checks if current locale is RTL (Right To Left).
boolean
Whether locale is RTL.
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.
object
Locale data configuration.
string
Domain for which configuration applies.
object
Hooks implementation.
object
I18n instance.

defaultI18n

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

subscribe( callback )

Subscribes to changes of locale data.
function
required
Subscription callback function.
function
Unsubscribe callback.

Version

Current version: 6.13.0