Title: @wordpress/i18n
Published: March 9, 2021
Last modified: September 16, 2026

---

# @wordpress/i18n

## In this article

 * [Installation](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/?output_format=md#installation)
 * [Usage](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/?output_format=md#usage)
 * [API](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/?output_format=md#api)
    - [createI18n](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/?output_format=md#createi18n)
    - [defaultI18n](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/?output_format=md#defaulti18n)
    - [getLocaleData](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/?output_format=md#getlocaledata)
    - [hasTranslation](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/?output_format=md#hastranslation)
    - [isRTL](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/?output_format=md#isrtl)
    - [resetLocaleData](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/?output_format=md#resetlocaledata)
    - [setLocaleData](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/?output_format=md#setlocaledata)
    - [sprintf](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/?output_format=md#sprintf)
    - [subscribe](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/?output_format=md#subscribe)
    - [_n](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/?output_format=md#n)
    - [_nx](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/?output_format=md#nx)
    - [_x](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/?output_format=md#x)
    - [__](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/?output_format=md#)
 * [Contributing to this package](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/?output_format=md#contributing-to-this-package)

[ Back to top](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/?output_format=md#wp--skip-link--target)

Internationalization utilities for client-side localization. See [How to Internationalize Your Plugin](https://developer.wordpress.org/plugins/internationalization/how-to-internationalize-your-plugin/)
for server-side documentation.

## 󠀁[Installation](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/?output_format=md#installation)󠁿

Install the module:

    ```bash
    npm install @wordpress/i18n --save
    ```

_This package assumes that your code will run in an **ES2015+** environment. If 
you’re using an environment that has limited or no support for such language features
and APIs, you should include [the polyfill shipped in `@wordpress/babel-preset-default`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/babel-preset-default#polyfill)
in your code._

## 󠀁[Usage](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/?output_format=md#usage)󠁿

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

    sprintf( _n( '%d hat', '%d hats', 4, 'text-domain' ), 4 );
    // 4 hats
    ```

For a complete example, see the [Internationalization section of the Block Editor Handbook](https://developer.wordpress.org/block-editor/developers/internationalization/).

## 󠀁[API](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/?output_format=md#api)󠁿

### 󠀁[createI18n](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/?output_format=md#createi18n)󠁿

Create an i18n instance

_Parameters_

 * _initialData_ `[LocaleData< TextDomain >]`: Locale data configuration.
 * _initialDomain_ `[TextDomain]`: Domain for which configuration applies.
 * _hooks_ `[Hooks]`: Hooks implementation.

_Returns_

 * `I18n< TextDomain >`: I18n instance.

### 󠀁[defaultI18n](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/?output_format=md#defaulti18n)󠁿

Default, singleton instance of `I18n`.

### 󠀁[getLocaleData](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/?output_format=md#getlocaledata)󠁿

Returns locale data by domain in a Jed-formatted JSON object shape.

_Related_

 * [http://messageformat.github.io/Jed/](http://messageformat.github.io/Jed/)

_Parameters_

 * _domain_ `[ string | undefined ]`: Domain for which to get the data.

_Returns_

 * `LocaleData`: Locale data.

### 󠀁[hasTranslation](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/?output_format=md#hastranslation)󠁿

Check if there is a translation for a given string (in singular form).

_Parameters_

 * _single_ `string`: Singular form of the string to look up.
 * _context_ `string`: Context information for the translators.
 * _domain_ `string`: Domain to retrieve the translated text.

_Returns_

 * `boolean`: Whether the translation exists or not.

### 󠀁[isRTL](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/?output_format=md#isrtl)󠁿

Check if current locale is RTL.

**RTL (Right To Left)** is a locale property indicating that text is written from
right to left. For example, the `he` locale (for Hebrew) specifies right-to-left.
Arabic (ar) is another common language written RTL. The opposite of RTL, LTR (Left
To Right) is used in other languages, including English (`en`, `en-US`, `en-GB`,
etc.), Spanish (`es`), and French (`fr`).

_Returns_

 * `boolean`: Whether locale is RTL.

### 󠀁[resetLocaleData](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/?output_format=md#resetlocaledata)󠁿

Resets all current Tannin instance locale data and sets the specified locale data
for the domain. Accepts data in a Jed-formatted JSON object shape.

_Related_

 * [http://messageformat.github.io/Jed/](http://messageformat.github.io/Jed/)

_Parameters_

 * _data_ `[LocaleData]`: Locale data configuration.
 * _domain_ `[string | undefined]`: Domain for which configuration applies.

### 󠀁[setLocaleData](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/?output_format=md#setlocaledata)󠁿

Merges locale data into the Tannin instance by domain. Accepts data in a Jed-formatted
JSON object shape.

_Related_

 * [http://messageformat.github.io/Jed/](http://messageformat.github.io/Jed/)

_Parameters_

 * _data_ `[LocaleData ]`: Locale data configuration.
 * _domain_ `[string | undefined]`: Domain for which configuration applies.

### 󠀁[sprintf](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/?output_format=md#sprintf)󠁿

Returns a formatted string.

_Related_

 * [https://www.npmjs.com/package/@tannin/sprintf](https://www.npmjs.com/package/@tannin/sprintf)

_Parameters_

 * _format_ `T | TransformedText< T >`: The format of the string to generate.
 * _args_ `DistributeSprintfArgs< T >`: Arguments to apply to the format.

_Returns_

 * `TransformedText< T >`: The formatted string.

### 󠀁[subscribe](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/?output_format=md#subscribe)󠁿

Subscribes to changes of locale data

_Parameters_

 * _callback_ `SubscribeCallback`: Subscription callback

_Returns_

 * `UnsubscribeCallback`: Unsubscribe callback

### 󠀁[_n](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/?output_format=md#n)󠁿

Translates and retrieves the singular or plural form based on the supplied number.

_Related_

 * [https://developer.wordpress.org/reference/functions/_n/](https://developer.wordpress.org/reference/functions/_n/)

_Parameters_

 * _single_ `Single`: The text to be used if the number is singular.
 * _plural_ `Plural`: The text to be used if the number is plural.
 * _number_ `number`: The number to compare against to use either the singular or
   plural form.
 * _domain_ `string | undefined`: Domain to retrieve the translated text.

_Returns_

 * `TransformedText<Single | Plural>`: The translated singular or plural form.

### 󠀁[_nx](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/?output_format=md#nx)󠁿

Translates and retrieves the singular or plural form based on the supplied number,
with gettext context.

_Related_

 * [https://developer.wordpress.org/reference/functions/_nx/](https://developer.wordpress.org/reference/functions/_nx/)

_Parameters_

 * _single_ `Single`: The text to be used if the number is singular.
 * _single_ `Single`: The text to be used if the number is singular.
 * _plural_ `Plural`: The text to be used if the number is plural.
 * _number_ `number`: The number to compare against to use either the singular or
   plural form.
 * _context_ `string`: Context information for the translators.
 * _domain_ `[string | undefined]`: Domain to retrieve the translated text.

_Returns_

 * `TransformedText<Single | Plural>`: The translated singular or plural form.

### 󠀁[_x](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/?output_format=md#x)󠁿

Retrieve translated string with gettext context.

_Related_

 * [https://developer.wordpress.org/reference/functions/_x/](https://developer.wordpress.org/reference/functions/_x/)

_Parameters_

 * _text_ `Text`: Text to translate.
 * _context_ `string`: Context information for the translators.
 * _domain_ `string | undefined`: Domain to retrieve the translated text.

_Returns_

 * `TransformedText<Text>`: Translated context string without pipe.

### 󠀁[__](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/?output_format=md#)󠁿

Retrieve the translation of text.

_Related_

 * [https://developer.wordpress.org/reference/functions/__/](https://developer.wordpress.org/reference/functions/__/)

_Parameters_

 * _text_ `Text`: Text to translate.
 * _domain_ `string | undefined`: Domain to retrieve the translated text.

_Returns_

 * `TransformedText<Text>`: Translated text.

## 󠀁[Contributing to this package](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/?output_format=md#contributing-to-this-package)󠁿

This is an individual package that’s part of the Gutenberg project. The project 
is organized as a monorepo. It’s made up of multiple self-contained software packages,
each with a specific purpose. The packages in this monorepo are published to [npm](https://www.npmjs.com/)
and used by [WordPress](https://make.wordpress.org/core/) as well as other software
projects.

To find out more about contributing to this package or Gutenberg as a whole, please
read the project’s main [contributor guide](https://github.com/WordPress/gutenberg/tree/HEAD/CONTRIBUTING.md).

First published

March 9, 2021

Last updated

September 16, 2026

Edit article

[ Improve it on GitHub: @wordpress/i18n ](https://github.com/WordPress/gutenberg/edit/trunk/packages/i18n/README.md)

[  Previous: @wordpress/html-entities](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-html-entities/)

[  Next: @wordpress/icons](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-icons/)