Dev note for introduction of i18n Filters & createI18n() changes

dev-note.md

New i18n filters & createI18n() changes

New i18n filters

The Javascript i18n functions (__(), _x(), _n() and _nx()) provide translations of strings for use in your code. The values returned by these functions are now filterable if you need to override them, using the following filters:

• i18n.gettext
• i18n.gettext_with_context
• i18n.ngettext
• i18n.ngettext_with_context

Note: Text domain-specific versions of these filters are also available, see below for more details.

Filter Arguments

The filters are passed the following arguments, in line with their PHP equivalents.

i18n.gettext

function i18nGettextCallback( translation, text, domain ) {
	return translation;
}

i18n.gettext_with_context

function i18nGettextWithContextCallback( translation, text, context, domain ) {
	return translation;
}

i18n.ngettext

function i18nNgettextCallback( translation, single, plural, number, domain ) {
	return translation;
}

i18n.ngettext_with_context

function i18nNgettextWithContextCallback(
	translation,
	single,
	plural,
	number,
	context,
	domain
) {
	return translation;
}

Basic Example

Here is a simple example, using the i18n.gettext filter to override a specific translation.

// Define our filter callback.
function myPluginGettextFilter( translation, text, domain ) {
	if ( text === 'Add to Reusable blocks' ) {
		return 'Save to MyOrg block library';
	}
	return translation;
}

// Adding the filter
wp.hooks.addFilter(
    'i18n.gettext',
    'my-plugin/override-add-to-reusable-blocks-label',
    myPluginGettextFilter
);

Using 'text domain'-specific filters

Filters that are specific to the text domain you're operating on are generally preferred for performance reasons (since your callback will only be run for strings in the relevant text domain).

To attach to a text domain-specific filter append an underscore and the text-domain to the standard filter name. For example, if filtering a string where the text domain is "woocommerce", you would use one of the following filters:

• i18n.gettext_woocommerce
• i18n.gettext_with_context_woocommerce
• i18n.ngettext_woocommerce
• i18n.ngettext_with_context_woocommerce

For example:

// Define our filter callback.
function myPluginGettextFilter( translation, text, domain ) {
	if ( text === "You’ve fulfilled all your orders" ) {
		return 'All packed up and ready to go. Good job!';
	}
	return translation;
}

// Adding the filter
wp.hooks.addFilter(
	'i18n.gettext_woocommerce',
	'my-plugin/override-fulfilled-all-orders-text',
	myPluginGettextFilter
);

To apply a filter where the text-domain is undefined (for example WordPress core strings), then use "default" to construct the filter name.

• i18n.gettext_default
• i18n.gettext_with_context_default
• i18n.ngettext_default
• i18n.ngettext_with_context_default

Changes to createI18n()

In order to support the filtering of translated strings, the createI18n() method that creates an i18n instance now allows a @wordpress/hooks instance to be passed in.

If you are directly creating an i18n instance yourself by calling createi18n() and you wish to take advantage of filtering, then you will need to update your code to supply a suitable third argument.

Note: If you are using the existing translation functions provided by @wordpress/i18n then you do not need to do anything, the default i18n instance is already set up correctly.

Use standard wp.hooks instance when creating an i18n Instance

import { createI18n } from "@wordpress/i18n";
import "@wordpress/hooks";

const myI18n = createI18n( initialData, initialDomain, wp.hooks );

Use separate hooks instance when creating an i18n Instance

import { createI18n } from "@wordpress/i18n";
import { createHooks } from "@wordpress/hooks";

const myHooks = createHooks();
const myI18n  = createI18n( initialData, initialDomain, myHooks );