Internationalization (i18n)

Internationalization utilities for client-side localization. See How to Internationalize Your Plugin for server-side documentation.

Installation

Install the module:

npm install @aarondewes/wp-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 ES2015+ such as IE browsers then using core-js will add polyfills for these methods.

Usage

import { sprintf, _n } from '@aarondewes/wp-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.

API

# createI18n

Create an i18n instance

Parameters

• initialData [LocaleData]: Locale data configuration.
• initialDomain [string]: Domain for which configuration applies.
• hooks [Hooks]: Hooks implementation.

Returns

• I18n: I18n instance

# defaultI18n

Default, singleton instance of I18n.

# getLocaleData

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

Related

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

Parameters

• domain [string]: Domain for which to get the data.

Returns

• LocaleData: Locale data.

# 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

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

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/

Parameters

• data [LocaleData]: Locale data configuration.
• domain [string]: Domain for which configuration applies.

# 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/

Parameters

• data [LocaleData]: Locale data configuration.
• domain [string]: Domain for which configuration applies.

# sprintf

Returns a formatted string. If an error occurs in applying the format, the original format string is returned.

Related

• https://www.npmjs.com/package/sprintf-js

Parameters

• format string: The format of the string to generate.
• args ...*: Arguments to apply to the format.

Returns

• string: The formatted string.

# subscribe

Subscribes to changes of locale data

Parameters

• callback SubscribeCallback: Subscription callback

Returns

• UnsubscribeCallback: Unsubscribe callback

# _n

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

Related

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

Parameters

• single string: The text to be used if the number is singular.
• plural string: 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]: Domain to retrieve the translated text.

Returns

• string: The translated singular or plural form.

# _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/

Parameters

• single string: The text to be used if the number is singular.
• plural string: 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]: Domain to retrieve the translated text.

Returns

• string: The translated singular or plural form.

# _x

Retrieve translated string with gettext context.

Related

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

Parameters

• text string: Text to translate.
• context string: Context information for the translators.
• domain [string]: Domain to retrieve the translated text.

Returns

• string: Translated context string without pipe.

# __

Retrieve the translation of text.

Related

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

Parameters

• text string: Text to translate.
• domain [string]: Domain to retrieve the translated text.

Returns

• string: Translated text.