@wordpress/i18n

What is @wordpress/i18n?

@wordpress/i18n is a package designed to provide internationalization (i18n) support for WordPress projects. It allows developers to easily translate strings and manage localization in their WordPress plugins and themes.

What are @wordpress/i18n's main functionalities?

Translating Strings

The `__` function is used to translate a string. The first argument is the string to be translated, and the second argument is the text domain.

const { __ } = require('@wordpress/i18n');
const translatedString = __('Hello, world!', 'text-domain');
console.log(translatedString);

Translating with Context

The `_x` function is used to translate a string with context. The first argument is the string to be translated, the second argument is the context, and the third argument is the text domain.

const { _x } = require('@wordpress/i18n');
const translatedString = _x('Post', 'noun', 'text-domain');
console.log(translatedString);

Plural Translations

The `_n` function is used for plural translations. The first argument is the singular form, the second argument is the plural form, the third argument is the number, and the fourth argument is the text domain.

const { _n } = require('@wordpress/i18n');
const translatedString = _n('%d post', '%d posts', 2, 'text-domain');
console.log(translatedString);

Translating with Context and Plural

The `_nx` function is used for plural translations with context. The first argument is the singular form, the second argument is the plural form, the third argument is the number, the fourth argument is the context, and the fifth argument is the text domain.

const { _nx } = require('@wordpress/i18n');
const translatedString = _nx('%d comment', '%d comments', 2, 'noun', 'text-domain');
console.log(translatedString);

Other packages similar to @wordpress/i18n

i18next

i18next is a popular internationalization framework for JavaScript. It provides a complete solution for localizing applications, including support for pluralization, context, and interpolation. Compared to @wordpress/i18n, i18next offers more advanced features and is suitable for a wider range of applications beyond WordPress.

react-intl

react-intl is a library for internationalizing React applications. It provides components and an API to format dates, numbers, and strings, and to handle pluralization and translations. While @wordpress/i18n is tailored for WordPress, react-intl is specifically designed for React applications.

polyglot

Polyglot.js is a small library for internationalizing JavaScript applications. It provides a simple API for translating strings and handling pluralization. Polyglot.js is more lightweight compared to @wordpress/i18n and is suitable for projects that require basic i18n support.

README

Internationalization (i18n)

Internationalization utilities for client-side localization.

https://codex.wordpress.org/I18n_for_WordPress_Developers

Installation

Install the module:

npm install @wordpress/i18n --save

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

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

Note that you will not need to specify domain for the strings.

Build

You can use the WordPress i18n babel plugin to generate a .pot file containing all your localized strings.

The package also includes a pot-to-php script used to generate a php files containing the messages listed in a .pot file. This is useful to trick WordPress.org translation strings discovery since at the moment, WordPress.org is not capable of parsing strings directly from JavaScript files.

npx pot-to-php languages/myplugin.pot languages/myplugin-translations.php text-domain

API

__( text: string, domain: string ): string

Retrieve the translation of text.

See: https://developer.wordpress.org/reference/functions/__/

_x( text: string, context: string, domain: string ): string

Retrieve translated string with gettext context.

See: https://developer.wordpress.org/reference/functions/_x/

_n( single: string, plural: string, number: Number, domain: string ): string

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

See: https://developer.wordpress.org/reference/functions/_n/

_nx( single: string, plural: string, number: Number, context: string, domain: string ): string

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

See: https://developer.wordpress.org/reference/functions/_nx/

sprintf( format: string, ...args: mixed[] ): string

Returns a formatted string.

See: http://www.diveintojavascript.com/projects/javascript-sprintf

setLocaleData( data: Object, domain: string )

Creates a new Jed instance with specified locale data configuration.

getI18n(): Jed

Returns the current Jed instance, initializing with a default configuration if not already assigned.

See: http://messageformat.github.io/Jed/