New i18n filters & createI18n() changes

New i18ni18n Internationalization, or the act of writing and preparing code to be fully translatable into other languages. Also see localization. Often written with a lowercase i so it is not confused with a lowercase L or the numeral 1. Often an acquired skill. filters

The JavascriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. 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.

FilterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. Arguments

The filters are passed the following arguments, in line with their PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher 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 translationtranslation The process (or result) of changing text, words, and display formatting to support another language. Also see localization, internationalization..

// 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 coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. 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.hooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same. 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 );

This dev notedev note Each important change in WordPress Core is documented in a developers note, (usually called dev note). Good dev notes generally include: a description of the change; the decision that led to this change a description of how developers are supposed to work with that change. Dev notes are published on Make/Core blog during the beta phase of WordPress release cycle. Publishing dev notes is particularly important when plugin/theme authors and WordPress developers need to be aware of those changes.In general, all dev notes are compiled into a Field Guide at the beginning of the release candidate phase. was written by @leewillis77.

#5-7, #block-editor, #dev-notes