@wordpress/i18n - npm Package Compare versions

Comparing version 3.17.1-next.0 to 3.17.1-next.1

build-module/create-i18n.js

@@ -30,6 +30,20 @@ import _defineProperty from "@babel/runtime/helpers/esm/defineProperty";
 };
-/* eslint-disable jsdoc/valid-types */
+/*
+ * Regular expression that matches i18n hooks like `i18n.gettext`, `i18n.ngettext`,
+ * `i18n.gettext_domain` or `i18n.ngettext_with_context` or `i18n.has_translation`.
+ */
 
+var I18N_HOOK_REGEXP = /^i18n\.(n?gettext|has_translation)(_|$)/;
 /**
+ * @typedef {(domain?: string) => LocaleData} GetLocaleData
+ *
+ * Returns locale data by domain in a
+ * Jed-formatted JSON object shape.
+ *
+ * @see http://messageformat.github.io/Jed/
+ */
+
+/**
  * @typedef {(data?: LocaleData, domain?: string) => void} SetLocaleData
+ *
  * Merges locale data into the Tannin instance by domain. Accepts data in a
@@ -41,3 +55,18 @@ * Jed-formatted JSON object shape.
 
+/** @typedef {() => void} SubscribeCallback */
+
+/** @typedef {() => void} UnsubscribeCallback */
+
 /**
+ * @typedef {(callback: SubscribeCallback) => UnsubscribeCallback} Subscribe
+ *
+ * Subscribes to changes of locale data
+ */
+
+/**
+ * @typedef {(domain?: string) => string} GetFilterDomain
+ * Retrieve the domain to use when calling domain-specific filters.
+ */
+
+/**
  * @typedef {(text: string, domain?: string) => string} __
@@ -87,4 +116,10 @@ *
 
-/* eslint-enable jsdoc/valid-types */
+/**
+ * @typedef {(single: string, context?: string, domain?: string) => boolean} HasTranslation
+ *
+ * Check if there is a translation for a given string in singular form.
+ */
 
+/** @typedef {import('@wordpress/hooks').Hooks} Hooks */
+
 /**
@@ -94,4 +129,6 @@ * An i18n instance
  * @typedef I18n
+ * @property {GetLocaleData} getLocaleData Returns locale data by domain in a Jed-formatted JSON object shape.
  * @property {SetLocaleData} setLocaleData Merges locale data into the Tannin instance by domain. Accepts data in a
  *                                         Jed-formatted JSON object shape.
+ * @property {Subscribe} subscribe         Subscribes to changes of Tannin locale data.
  * @property {__} __                       Retrieve the translation of text.
@@ -104,2 +141,3 @@ * @property {_x} _x                       Retrieve translated string with gettext context.
  * @property {IsRtl} isRTL                 Check if current locale is RTL.
+ * @property {HasTranslation} hasTranslation Check if there is a translation for a given string.
  */
@@ -112,6 +150,7 @@
  * @param {string}     [initialDomain]  Domain for which configuration applies.
+ * @param {Hooks} [hooks]     Hooks implementation.
  * @return {I18n}                       I18n instance
  */
 
-export var createI18n = function createI18n(initialData, initialDomain) {
+export var createI18n = function createI18n(initialData, initialDomain, hooks) {
   /**
@@ -123,5 +162,37 @@ * The underlying instance of Tannin to which exported functions interface.
   var tannin = new Tannin({});
-  /** @type {SetLocaleData} */
+  var listeners = new Set();
 
-  var setLocaleData = function setLocaleData(data) {
+  var notifyListeners = function notifyListeners() {
+    listeners.forEach(function (listener) {
+      return listener();
+    });
+  };
+  /**
+   * Subscribe to changes of locale data.
+   *
+   * @param {SubscribeCallback} callback Subscription callback.
+   * @return {UnsubscribeCallback} Unsubscribe callback.
+   */
+
+
+  var subscribe = function subscribe(callback) {
+    listeners.add(callback);
+    return function () {
+      return listeners.delete(callback);
+    };
+  };
+  /** @type {GetLocaleData} */
+
+
+  var getLocaleData = function getLocaleData() {
+    var domain = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : 'default';
+    return tannin.data[domain];
+  };
+  /**
+   * @param {LocaleData} [data]
+   * @param {string} [domain]
+   */
+
+
+  var doSetLocaleData = function doSetLocaleData(data) {
     var domain = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 'default';
@@ -133,2 +204,9 @@ tannin.data[domain] = _objectSpread(_objectSpread(_objectSpread({}, DEFAULT_LOCALE_DATA), tannin.data[domain]), data); // Populate default domain configuration (supported locale date which omits
   };
+  /** @type {SetLocaleData} */
+
+
+  var setLocaleData = function setLocaleData(data, domain) {
+    doSetLocaleData(data, domain);
+    notifyListeners();
+  };
   /**
@@ -159,3 +237,4 @@ * Wrapper for Tannin's `dcnpgettext`. Populates default locale data if not
     if (!tannin.data[domain]) {
-      setLocaleData(undefined, domain);
+      // use `doSetLocaleData` to set silently, without notifying listeners
+      doSetLocaleData(undefined, domain);
     }
@@ -165,2 +244,9 @@
   };
+  /** @type {GetFilterDomain} */
+
+
+  var getFilterDomain = function getFilterDomain() {
+    var domain = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : 'default';
+    return domain;
+  };
   /** @type {__} */
@@ -170,3 +256,27 @@
   var __ = function __(text, domain) {
-    return dcnpgettext(domain, undefined, text);
+    var translation = dcnpgettext(domain, undefined, text);
+
+    if (!hooks) {
+      return translation;
+    }
+    /**
+     * Filters text with its translation.
+     *
+     * @param {string} translation Translated text.
+     * @param {string} text        Text to translate.
+     * @param {string} domain      Text domain. Unique identifier for retrieving translated strings.
+     */
+
+
+    translation =
+    /** @type {string} */
+
+    /** @type {*} */
+    hooks.applyFilters('i18n.gettext', translation, text, domain);
+    return (
+      /** @type {string} */
+
+      /** @type {*} */
+      hooks.applyFilters('i18n.gettext_' + getFilterDomain(domain), translation, text, domain)
+    );
   };
@@ -177,3 +287,28 @@ /** @type {_x} */
   var _x = function _x(text, context, domain) {
-    return dcnpgettext(domain, context, text);
+    var translation = dcnpgettext(domain, context, text);
+
+    if (!hooks) {
+      return translation;
+    }
+    /**
+     * Filters text with its translation based on context information.
+     *
+     * @param {string} translation Translated text.
+     * @param {string} text        Text to translate.
+     * @param {string} context     Context information for the translators.
+     * @param {string} domain      Text domain. Unique identifier for retrieving translated strings.
+     */
+
+
+    translation =
+    /** @type {string} */
+
+    /** @type {*} */
+    hooks.applyFilters('i18n.gettext_with_context', translation, text, context, domain);
+    return (
+      /** @type {string} */
+
+      /** @type {*} */
+      hooks.applyFilters('i18n.gettext_with_context_' + getFilterDomain(domain), translation, text, context, domain)
+    );
   };
@@ -184,3 +319,29 @@ /** @type {_n} */
   var _n = function _n(single, plural, number, domain) {
-    return dcnpgettext(domain, undefined, single, plural, number);
+    var translation = dcnpgettext(domain, undefined, single, plural, number);
+
+    if (!hooks) {
+      return translation;
+    }
+    /**
+     * Filters the singular or plural form of a string.
+     *
+     * @param {string} translation Translated text.
+     * @param {string} single      The text to be used if the number is singular.
+     * @param {string} plural      The text to be used if the number is plural.
+     * @param {string} number      The number to compare against to use either the singular or plural form.
+     * @param {string} domain      Text domain. Unique identifier for retrieving translated strings.
+     */
+
+
+    translation =
+    /** @type {string} */
+
+    /** @type {*} */
+    hooks.applyFilters('i18n.ngettext', translation, single, plural, number, domain);
+    return (
+      /** @type {string} */
+
+      /** @type {*} */
+      hooks.applyFilters('i18n.ngettext_' + getFilterDomain(domain), translation, single, plural, number, domain)
+    );
   };
@@ -191,3 +352,30 @@ /** @type {_nx} */
   var _nx = function _nx(single, plural, number, context, domain) {
-    return dcnpgettext(domain, context, single, plural, number);
+    var translation = dcnpgettext(domain, context, single, plural, number);
+
+    if (!hooks) {
+      return translation;
+    }
+    /**
+     * Filters the singular or plural form of a string with gettext context.
+     *
+     * @param {string} translation Translated text.
+     * @param {string} single      The text to be used if the number is singular.
+     * @param {string} plural      The text to be used if the number is plural.
+     * @param {string} number      The number to compare against to use either the singular or plural form.
+     * @param {string} context     Context information for the translators.
+     * @param {string} domain      Text domain. Unique identifier for retrieving translated strings.
+     */
+
+
+    translation =
+    /** @type {string} */
+
+    /** @type {*} */
+    hooks.applyFilters('i18n.ngettext_with_context', translation, single, plural, number, context, domain);
+    return (
+      /** @type {string} */
+
+      /** @type {*} */
+      hooks.applyFilters('i18n.ngettext_with_context_' + getFilterDomain(domain), translation, single, plural, number, context, domain)
+    );
   };
@@ -200,3 +388,35 @@ /** @type {IsRtl} */
   };
+  /** @type {HasTranslation} */
 
+
+  var hasTranslation = function hasTranslation(single, context, domain) {
+    var _tannin$data, _tannin$data2;
+
+    var key = context ? context + "\x04" + single : single;
+    var result = !!((_tannin$data = tannin.data) !== null && _tannin$data !== void 0 && (_tannin$data2 = _tannin$data[domain !== null && domain !== void 0 ? domain : 'default']) !== null && _tannin$data2 !== void 0 && _tannin$data2[key]);
+
+    if (hooks) {
+      /**
+       * Filters the presence of a translation in the locale data.
+       *
+       * @param {boolean} hasTranslation Whether the translation is present or not..
+       * @param {string} single The singular form of the translated text (used as key in locale data)
+       * @param {string} context Context information for the translators.
+       * @param {string} domain Text domain. Unique identifier for retrieving translated strings.
+       */
+      result =
+      /** @type { boolean } */
+
+      /** @type {*} */
+      hooks.applyFilters('i18n.has_translation', result, single, context, domain);
+      result =
+      /** @type { boolean } */
+
+      /** @type {*} */
+      hooks.applyFilters('i18n.has_translation_' + getFilterDomain(domain), result, single, context, domain);
+    }
+
+    return result;
+  };
+
   if (initialData) {
@@ -206,4 +426,20 @@ setLocaleData(initialData, initialDomain);
 
+  if (hooks) {
+    /**
+     * @param {string} hookName
+     */
+    var onHookAddedOrRemoved = function onHookAddedOrRemoved(hookName) {
+      if (I18N_HOOK_REGEXP.test(hookName)) {
+        notifyListeners();
+      }
+    };
+
+    hooks.addAction('hookAdded', 'core/i18n', onHookAddedOrRemoved);
+    hooks.addAction('hookRemoved', 'core/i18n', onHookAddedOrRemoved);
+  }
+
   return {
+    getLocaleData: getLocaleData,
     setLocaleData: setLocaleData,
+    subscribe: subscribe,
     __: __,
@@ -213,5 +449,6 @@ _x: _x,
     _nx: _nx,
-    isRTL: isRTL
+    isRTL: isRTL,
+    hasTranslation: hasTranslation
   };
 };
 //# sourceMappingURL=create-i18n.js.map

build-module/default-i18n.js

@@ -5,3 +5,13 @@ /**
 import { createI18n } from './create-i18n';
-var i18n = createI18n();
+/**
+ * WordPress dependencies
+ */
+
+import { defaultHooks } from '@wordpress/hooks';
+var i18n = createI18n(undefined, undefined, defaultHooks);
+/**
+ * Default, singleton instance of `I18n`.
+ */
+
+export default i18n;
 /*
@@ -14,5 +24,17 @@ * Comments in this file are duplicated from ./i18n due to
  * @typedef {import('./create-i18n').LocaleData} LocaleData
+ * @typedef {import('./create-i18n').SubscribeCallback} SubscribeCallback
+ * @typedef {import('./create-i18n').UnsubscribeCallback} UnsubscribeCallback
  */
 
 /**
+ * Returns locale data by domain in a Jed-formatted JSON object shape.
+ *
+ * @see http://messageformat.github.io/Jed/
+ *
+ * @param {string} [domain] Domain for which to get the data.
+ * @return {LocaleData} Locale data.
+ */
+
+export var getLocaleData = i18n.getLocaleData.bind(i18n);
+/**
  * Merges locale data into the Tannin instance by domain. Accepts data in a
@@ -29,2 +51,10 @@ * Jed-formatted JSON object shape.
 /**
+ * Subscribes to changes of locale data
+ *
+ * @param {SubscribeCallback} callback Subscription callback
+ * @return {UnsubscribeCallback} Unsubscribe callback
+ */
+
+export var subscribe = i18n.subscribe.bind(i18n);
+/**
  * Retrieve the translation of text.
@@ -99,2 +129,12 @@ *
 export var isRTL = i18n.isRTL.bind(i18n);
+/**
+ * Check if there is a translation for a given string (in singular form).
+ *
+ * @param {string} single Singular form of the string to look up.
+ * @param {string} [context] Context information for the translators.
+ * @param {string} [domain] Domain to retrieve the translated text.
+ * @return {boolean} Whether the translation exists or not.
+ */
+
+export var hasTranslation = i18n.hasTranslation.bind(i18n);
 //# sourceMappingURL=default-i18n.js.map

build-module/index.js

 export { sprintf } from './sprintf';
 export * from './create-i18n';
-export { setLocaleData, __, _x, _n, _nx, isRTL } from './default-i18n';
+export { default as defaultI18n, setLocaleData, getLocaleData, subscribe, __, _x, _n, _nx, isRTL, hasTranslation } from './default-i18n';
 //# sourceMappingURL=index.js.map

build-types/create-i18n.d.ts

@@ -1,2 +0,2 @@
-export function createI18n(initialData?: Record<string, any> | undefined, initialDomain?: string | undefined): I18n;
+export function createI18n(initialData?: Record<string, any> | undefined, initialDomain?: string | undefined, hooks?: import("@wordpress/hooks/build-types/createHooks")._Hooks | undefined): I18n;
 export type LocaleData = {
@@ -6,2 +6,7 @@ [x: string]: any;
 /**
+ * Returns locale data by domain in a
+ * Jed-formatted JSON object shape.
+ */
+export type GetLocaleData = (domain?: string | undefined) => LocaleData;
+/**
  * Merges locale data into the Tannin instance by domain. Accepts data in a
@@ -11,3 +16,13 @@ * Jed-formatted JSON object shape.
 export type SetLocaleData = (data?: Record<string, any> | undefined, domain?: string | undefined) => void;
+export type SubscribeCallback = () => void;
+export type UnsubscribeCallback = () => void;
 /**
+ * Subscribes to changes of locale data
+ */
+export type Subscribe = (callback: SubscribeCallback) => UnsubscribeCallback;
+/**
+ * Retrieve the domain to use when calling domain-specific filters.
+ */
+export type GetFilterDomain = (domain?: string | undefined) => string;
+/**
  * Retrieve the translation of text.
@@ -40,2 +55,7 @@ */
 /**
+ * Check if there is a translation for a given string in singular form.
+ */
+export type HasTranslation = (single: string, context?: string | undefined, domain?: string | undefined) => boolean;
+export type Hooks = import("@wordpress/hooks/build-types/createHooks")._Hooks;
+/**
  * An i18n instance
@@ -45,2 +65,6 @@ */
     /**
+     * Returns locale data by domain in a Jed-formatted JSON object shape.
+     */
+    getLocaleData: GetLocaleData;
+    /**
      * Merges locale data into the Tannin instance by domain. Accepts data in a
@@ -51,2 +75,6 @@ * Jed-formatted JSON object shape.
     /**
+     * Subscribes to changes of Tannin locale data.
+     */
+    subscribe: Subscribe;
+    /**
      * Retrieve the translation of text.
@@ -73,3 +101,7 @@ */
     isRTL: IsRtl;
+    /**
+     * Check if there is a translation for a given string.
+     */
+    hasTranslation: HasTranslation;
 };
 //# sourceMappingURL=create-i18n.d.ts.map

build-types/default-i18n.d.ts

@@ -0,5 +1,17 @@
+export default i18n;
 /**
  * @typedef {import('./create-i18n').LocaleData} LocaleData
+ * @typedef {import('./create-i18n').SubscribeCallback} SubscribeCallback
+ * @typedef {import('./create-i18n').UnsubscribeCallback} UnsubscribeCallback
  */
 /**
+ * Returns locale data by domain in a Jed-formatted JSON object shape.
+ *
+ * @see http://messageformat.github.io/Jed/
+ *
+ * @param {string} [domain] Domain for which to get the data.
+ * @return {LocaleData} Locale data.
+ */
+export const getLocaleData: import("./create-i18n").GetLocaleData;
+/**
  * Merges locale data into the Tannin instance by domain. Accepts data in a
@@ -13,4 +25,11 @@ * Jed-formatted JSON object shape.
  */
-export const setLocaleData: (data?: Record<string, any> | undefined, domain?: string | undefined) => void;
+export const setLocaleData: import("./create-i18n").SetLocaleData;
 /**
+ * Subscribes to changes of locale data
+ *
+ * @param {SubscribeCallback} callback Subscription callback
+ * @return {UnsubscribeCallback} Unsubscribe callback
+ */
+export const subscribe: import("./create-i18n").Subscribe;
+/**
  * Retrieve the translation of text.
@@ -25,3 +44,3 @@ *
  */
-export const __: (text: string, domain?: string | undefined) => string;
+export const __: import("./create-i18n").__;
 /**
@@ -38,3 +57,3 @@ * Retrieve translated string with gettext context.
  */
-export const _x: (text: string, context: string, domain?: string | undefined) => string;
+export const _x: import("./create-i18n")._x;
 /**
@@ -54,3 +73,3 @@ * Translates and retrieves the singular or plural form based on the supplied
  */
-export const _n: (single: string, plural: string, number: number, domain?: string | undefined) => string;
+export const _n: import("./create-i18n")._n;
 /**
@@ -71,3 +90,3 @@ * Translates and retrieves the singular or plural form based on the supplied
  */
-export const _nx: (single: string, plural: string, number: number, context: string, domain?: string | undefined) => string;
+export const _nx: import("./create-i18n")._nx;
 /**
@@ -83,6 +102,18 @@ * Check if current locale is RTL.
  */
-export const isRTL: () => boolean;
+export const isRTL: import("./create-i18n").IsRtl;
+/**
+ * Check if there is a translation for a given string (in singular form).
+ *
+ * @param {string} single Singular form of the string to look up.
+ * @param {string} [context] Context information for the translators.
+ * @param {string} [domain] Domain to retrieve the translated text.
+ * @return {boolean} Whether the translation exists or not.
+ */
+export const hasTranslation: import("./create-i18n").HasTranslation;
 export type LocaleData = {
     [x: string]: any;
 };
+export type SubscribeCallback = () => void;
+export type UnsubscribeCallback = () => void;
+declare const i18n: import("./create-i18n").I18n;
 //# sourceMappingURL=default-i18n.d.ts.map

build-types/index.d.ts

 export { sprintf } from "./sprintf";
 export * from "./create-i18n";
-export { setLocaleData, __, _x, _n, _nx, isRTL } from "./default-i18n";
+export { default as defaultI18n, setLocaleData, getLocaleData, subscribe, __, _x, _n, _nx, isRTL, hasTranslation } from "./default-i18n";
 //# sourceMappingURL=index.d.ts.map

build/create-i18n.js

@@ -36,6 +36,20 @@ "use strict";
 };
-/* eslint-disable jsdoc/valid-types */
+/*
+ * Regular expression that matches i18n hooks like `i18n.gettext`, `i18n.ngettext`,
+ * `i18n.gettext_domain` or `i18n.ngettext_with_context` or `i18n.has_translation`.
+ */
 
+var I18N_HOOK_REGEXP = /^i18n\.(n?gettext|has_translation)(_|$)/;
 /**
+ * @typedef {(domain?: string) => LocaleData} GetLocaleData
+ *
+ * Returns locale data by domain in a
+ * Jed-formatted JSON object shape.
+ *
+ * @see http://messageformat.github.io/Jed/
+ */
+
+/**
  * @typedef {(data?: LocaleData, domain?: string) => void} SetLocaleData
+ *
  * Merges locale data into the Tannin instance by domain. Accepts data in a
@@ -47,3 +61,18 @@ * Jed-formatted JSON object shape.
 
+/** @typedef {() => void} SubscribeCallback */
+
+/** @typedef {() => void} UnsubscribeCallback */
+
 /**
+ * @typedef {(callback: SubscribeCallback) => UnsubscribeCallback} Subscribe
+ *
+ * Subscribes to changes of locale data
+ */
+
+/**
+ * @typedef {(domain?: string) => string} GetFilterDomain
+ * Retrieve the domain to use when calling domain-specific filters.
+ */
+
+/**
  * @typedef {(text: string, domain?: string) => string} __
@@ -93,4 +122,10 @@ *
 
-/* eslint-enable jsdoc/valid-types */
+/**
+ * @typedef {(single: string, context?: string, domain?: string) => boolean} HasTranslation
+ *
+ * Check if there is a translation for a given string in singular form.
+ */
 
+/** @typedef {import('@wordpress/hooks').Hooks} Hooks */
+
 /**
@@ -100,4 +135,6 @@ * An i18n instance
  * @typedef I18n
+ * @property {GetLocaleData} getLocaleData Returns locale data by domain in a Jed-formatted JSON object shape.
  * @property {SetLocaleData} setLocaleData Merges locale data into the Tannin instance by domain. Accepts data in a
  *                                         Jed-formatted JSON object shape.
+ * @property {Subscribe} subscribe         Subscribes to changes of Tannin locale data.
  * @property {__} __                       Retrieve the translation of text.
@@ -110,2 +147,3 @@ * @property {_x} _x                       Retrieve translated string with gettext context.
  * @property {IsRtl} isRTL                 Check if current locale is RTL.
+ * @property {HasTranslation} hasTranslation Check if there is a translation for a given string.
  */
@@ -118,6 +156,7 @@
  * @param {string}     [initialDomain]  Domain for which configuration applies.
+ * @param {Hooks} [hooks]     Hooks implementation.
  * @return {I18n}                       I18n instance
  */
 
-var createI18n = function createI18n(initialData, initialDomain) {
+var createI18n = function createI18n(initialData, initialDomain, hooks) {
   /**
@@ -129,5 +168,37 @@ * The underlying instance of Tannin to which exported functions interface.
   var tannin = new _tannin.default({});
-  /** @type {SetLocaleData} */
+  var listeners = new Set();
 
-  var setLocaleData = function setLocaleData(data) {
+  var notifyListeners = function notifyListeners() {
+    listeners.forEach(function (listener) {
+      return listener();
+    });
+  };
+  /**
+   * Subscribe to changes of locale data.
+   *
+   * @param {SubscribeCallback} callback Subscription callback.
+   * @return {UnsubscribeCallback} Unsubscribe callback.
+   */
+
+
+  var subscribe = function subscribe(callback) {
+    listeners.add(callback);
+    return function () {
+      return listeners.delete(callback);
+    };
+  };
+  /** @type {GetLocaleData} */
+
+
+  var getLocaleData = function getLocaleData() {
+    var domain = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : 'default';
+    return tannin.data[domain];
+  };
+  /**
+   * @param {LocaleData} [data]
+   * @param {string} [domain]
+   */
+
+
+  var doSetLocaleData = function doSetLocaleData(data) {
     var domain = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 'default';
@@ -139,2 +210,9 @@ tannin.data[domain] = _objectSpread(_objectSpread(_objectSpread({}, DEFAULT_LOCALE_DATA), tannin.data[domain]), data); // Populate default domain configuration (supported locale date which omits
   };
+  /** @type {SetLocaleData} */
+
+
+  var setLocaleData = function setLocaleData(data, domain) {
+    doSetLocaleData(data, domain);
+    notifyListeners();
+  };
   /**
@@ -165,3 +243,4 @@ * Wrapper for Tannin's `dcnpgettext`. Populates default locale data if not
     if (!tannin.data[domain]) {
-      setLocaleData(undefined, domain);
+      // use `doSetLocaleData` to set silently, without notifying listeners
+      doSetLocaleData(undefined, domain);
     }
@@ -171,2 +250,9 @@
   };
+  /** @type {GetFilterDomain} */
+
+
+  var getFilterDomain = function getFilterDomain() {
+    var domain = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : 'default';
+    return domain;
+  };
   /** @type {__} */
@@ -176,3 +262,27 @@
   var __ = function __(text, domain) {
-    return dcnpgettext(domain, undefined, text);
+    var translation = dcnpgettext(domain, undefined, text);
+
+    if (!hooks) {
+      return translation;
+    }
+    /**
+     * Filters text with its translation.
+     *
+     * @param {string} translation Translated text.
+     * @param {string} text        Text to translate.
+     * @param {string} domain      Text domain. Unique identifier for retrieving translated strings.
+     */
+
+
+    translation =
+    /** @type {string} */
+
+    /** @type {*} */
+    hooks.applyFilters('i18n.gettext', translation, text, domain);
+    return (
+      /** @type {string} */
+
+      /** @type {*} */
+      hooks.applyFilters('i18n.gettext_' + getFilterDomain(domain), translation, text, domain)
+    );
   };
@@ -183,3 +293,28 @@ /** @type {_x} */
   var _x = function _x(text, context, domain) {
-    return dcnpgettext(domain, context, text);
+    var translation = dcnpgettext(domain, context, text);
+
+    if (!hooks) {
+      return translation;
+    }
+    /**
+     * Filters text with its translation based on context information.
+     *
+     * @param {string} translation Translated text.
+     * @param {string} text        Text to translate.
+     * @param {string} context     Context information for the translators.
+     * @param {string} domain      Text domain. Unique identifier for retrieving translated strings.
+     */
+
+
+    translation =
+    /** @type {string} */
+
+    /** @type {*} */
+    hooks.applyFilters('i18n.gettext_with_context', translation, text, context, domain);
+    return (
+      /** @type {string} */
+
+      /** @type {*} */
+      hooks.applyFilters('i18n.gettext_with_context_' + getFilterDomain(domain), translation, text, context, domain)
+    );
   };
@@ -190,3 +325,29 @@ /** @type {_n} */
   var _n = function _n(single, plural, number, domain) {
-    return dcnpgettext(domain, undefined, single, plural, number);
+    var translation = dcnpgettext(domain, undefined, single, plural, number);
+
+    if (!hooks) {
+      return translation;
+    }
+    /**
+     * Filters the singular or plural form of a string.
+     *
+     * @param {string} translation Translated text.
+     * @param {string} single      The text to be used if the number is singular.
+     * @param {string} plural      The text to be used if the number is plural.
+     * @param {string} number      The number to compare against to use either the singular or plural form.
+     * @param {string} domain      Text domain. Unique identifier for retrieving translated strings.
+     */
+
+
+    translation =
+    /** @type {string} */
+
+    /** @type {*} */
+    hooks.applyFilters('i18n.ngettext', translation, single, plural, number, domain);
+    return (
+      /** @type {string} */
+
+      /** @type {*} */
+      hooks.applyFilters('i18n.ngettext_' + getFilterDomain(domain), translation, single, plural, number, domain)
+    );
   };
@@ -197,3 +358,30 @@ /** @type {_nx} */
   var _nx = function _nx(single, plural, number, context, domain) {
-    return dcnpgettext(domain, context, single, plural, number);
+    var translation = dcnpgettext(domain, context, single, plural, number);
+
+    if (!hooks) {
+      return translation;
+    }
+    /**
+     * Filters the singular or plural form of a string with gettext context.
+     *
+     * @param {string} translation Translated text.
+     * @param {string} single      The text to be used if the number is singular.
+     * @param {string} plural      The text to be used if the number is plural.
+     * @param {string} number      The number to compare against to use either the singular or plural form.
+     * @param {string} context     Context information for the translators.
+     * @param {string} domain      Text domain. Unique identifier for retrieving translated strings.
+     */
+
+
+    translation =
+    /** @type {string} */
+
+    /** @type {*} */
+    hooks.applyFilters('i18n.ngettext_with_context', translation, single, plural, number, context, domain);
+    return (
+      /** @type {string} */
+
+      /** @type {*} */
+      hooks.applyFilters('i18n.ngettext_with_context_' + getFilterDomain(domain), translation, single, plural, number, context, domain)
+    );
   };
@@ -206,3 +394,35 @@ /** @type {IsRtl} */
   };
+  /** @type {HasTranslation} */
 
+
+  var hasTranslation = function hasTranslation(single, context, domain) {
+    var _tannin$data, _tannin$data2;
+
+    var key = context ? context + "\x04" + single : single;
+    var result = !!((_tannin$data = tannin.data) !== null && _tannin$data !== void 0 && (_tannin$data2 = _tannin$data[domain !== null && domain !== void 0 ? domain : 'default']) !== null && _tannin$data2 !== void 0 && _tannin$data2[key]);
+
+    if (hooks) {
+      /**
+       * Filters the presence of a translation in the locale data.
+       *
+       * @param {boolean} hasTranslation Whether the translation is present or not..
+       * @param {string} single The singular form of the translated text (used as key in locale data)
+       * @param {string} context Context information for the translators.
+       * @param {string} domain Text domain. Unique identifier for retrieving translated strings.
+       */
+      result =
+      /** @type { boolean } */
+
+      /** @type {*} */
+      hooks.applyFilters('i18n.has_translation', result, single, context, domain);
+      result =
+      /** @type { boolean } */
+
+      /** @type {*} */
+      hooks.applyFilters('i18n.has_translation_' + getFilterDomain(domain), result, single, context, domain);
+    }
+
+    return result;
+  };
+
   if (initialData) {
@@ -212,4 +432,20 @@ setLocaleData(initialData, initialDomain);
 
+  if (hooks) {
+    /**
+     * @param {string} hookName
+     */
+    var onHookAddedOrRemoved = function onHookAddedOrRemoved(hookName) {
+      if (I18N_HOOK_REGEXP.test(hookName)) {
+        notifyListeners();
+      }
+    };
+
+    hooks.addAction('hookAdded', 'core/i18n', onHookAddedOrRemoved);
+    hooks.addAction('hookRemoved', 'core/i18n', onHookAddedOrRemoved);
+  }
+
   return {
+    getLocaleData: getLocaleData,
     setLocaleData: setLocaleData,
+    subscribe: subscribe,
     __: __,
@@ -219,3 +455,4 @@ _x: _x,
     _nx: _nx,
-    isRTL: isRTL
+    isRTL: isRTL,
+    hasTranslation: hasTranslation
   };
@@ -222,0 +459,0 @@ };

build/default-i18n.js

@@ -6,10 +6,21 @@ "use strict";
 });
-exports.isRTL = exports._nx = exports._n = exports._x = exports.__ = exports.setLocaleData = void 0;
+exports.hasTranslation = exports.isRTL = exports._nx = exports._n = exports._x = exports.__ = exports.subscribe = exports.setLocaleData = exports.getLocaleData = exports.default = void 0;
 
 var _createI18n = require("./create-i18n");
 
+var _hooks = require("@wordpress/hooks");
+
 /**
  * Internal dependencies
  */
-var i18n = (0, _createI18n.createI18n)();
+
+/**
+ * WordPress dependencies
+ */
+var i18n = (0, _createI18n.createI18n)(undefined, undefined, _hooks.defaultHooks);
+/**
+ * Default, singleton instance of `I18n`.
+ */
+
+var _default = i18n;
 /*
@@ -22,5 +33,18 @@ * Comments in this file are duplicated from ./i18n due to
  * @typedef {import('./create-i18n').LocaleData} LocaleData
+ * @typedef {import('./create-i18n').SubscribeCallback} SubscribeCallback
+ * @typedef {import('./create-i18n').UnsubscribeCallback} UnsubscribeCallback
  */
 
 /**
+ * Returns locale data by domain in a Jed-formatted JSON object shape.
+ *
+ * @see http://messageformat.github.io/Jed/
+ *
+ * @param {string} [domain] Domain for which to get the data.
+ * @return {LocaleData} Locale data.
+ */
+
+exports.default = _default;
+var getLocaleData = i18n.getLocaleData.bind(i18n);
+/**
  * Merges locale data into the Tannin instance by domain. Accepts data in a
@@ -35,4 +59,14 @@ * Jed-formatted JSON object shape.
 
+exports.getLocaleData = getLocaleData;
 var setLocaleData = i18n.setLocaleData.bind(i18n);
 /**
+ * Subscribes to changes of locale data
+ *
+ * @param {SubscribeCallback} callback Subscription callback
+ * @return {UnsubscribeCallback} Unsubscribe callback
+ */
+
+exports.setLocaleData = setLocaleData;
+var subscribe = i18n.subscribe.bind(i18n);
+/**
  * Retrieve the translation of text.
@@ -48,3 +82,3 @@ *
 
-exports.setLocaleData = setLocaleData;
+exports.subscribe = subscribe;
 
@@ -121,3 +155,14 @@ var __ = i18n.__.bind(i18n);
 var isRTL = i18n.isRTL.bind(i18n);
+/**
+ * Check if there is a translation for a given string (in singular form).
+ *
+ * @param {string} single Singular form of the string to look up.
+ * @param {string} [context] Context information for the translators.
+ * @param {string} [domain] Domain to retrieve the translated text.
+ * @return {boolean} Whether the translation exists or not.
+ */
+
 exports.isRTL = isRTL;
+var hasTranslation = i18n.hasTranslation.bind(i18n);
+exports.hasTranslation = hasTranslation;
 //# sourceMappingURL=default-i18n.js.map

build/index.js

 "use strict";
 
+var _interopRequireWildcard = require("@babel/runtime/helpers/interopRequireWildcard");
+
 Object.defineProperty(exports, "__esModule", {
@@ -8,3 +10,6 @@ value: true
   sprintf: true,
+  defaultI18n: true,
   setLocaleData: true,
+  getLocaleData: true,
+  subscribe: true,
   __: true,
@@ -14,3 +19,4 @@ _x: true,
   _nx: true,
-  isRTL: true
+  isRTL: true,
+  hasTranslation: true
 };
@@ -23,2 +29,8 @@ Object.defineProperty(exports, "sprintf", {
 });
+Object.defineProperty(exports, "defaultI18n", {
+  enumerable: true,
+  get: function get() {
+    return _defaultI18n.default;
+  }
+});
 Object.defineProperty(exports, "setLocaleData", {
@@ -30,2 +42,14 @@ enumerable: true,
 });
+Object.defineProperty(exports, "getLocaleData", {
+  enumerable: true,
+  get: function get() {
+    return _defaultI18n.getLocaleData;
+  }
+});
+Object.defineProperty(exports, "subscribe", {
+  enumerable: true,
+  get: function get() {
+    return _defaultI18n.subscribe;
+  }
+});
 Object.defineProperty(exports, "__", {
@@ -61,2 +85,8 @@ enumerable: true,
 });
+Object.defineProperty(exports, "hasTranslation", {
+  enumerable: true,
+  get: function get() {
+    return _defaultI18n.hasTranslation;
+  }
+});
 
@@ -79,3 +109,3 @@ var _sprintf = require("./sprintf");
 
-var _defaultI18n = require("./default-i18n");
+var _defaultI18n = _interopRequireWildcard(require("./default-i18n"));
 //# sourceMappingURL=index.js.map

CHANGELOG.md

@@ -1,5 +0,14 @@
-<!-- Learn how to maintain this file at https://github.com/WordPress/gutenberg/tree/master/packages#maintaining-changelogs. -->
+<!-- Learn how to maintain this file at https://github.com/WordPress/gutenberg/tree/HEAD/packages#maintaining-changelogs. -->
 
 ## Unreleased
 
+## 3.19.0-next.0 (2021-02-26)
+
+### Enhancements
+
+- Export the default `I18n` instance as `defaultI18n`, in addition to already exported bound methods.
+- Add new `getLocaleData` method to get the internal Tannin locale data object.
+- Add new `subscribe` method to subscribe to changes in the internal locale data.
+- Add new `hasTranslation` method to determine whether a translation for a string is available.
+
 ## 3.17.0 (2020-12-17)
@@ -6,0 +15,0 @@

package.json

 {
 	"name": "@wordpress/i18n",
-	"version": "3.17.1-next.0",
+	"version": "3.17.1-next.1+c95ee08bb",
 	"description": "WordPress internationalization (i18n) library.",
@@ -12,3 +12,3 @@ "author": "The WordPress Contributors",
 	],
-	"homepage": "https://github.com/WordPress/gutenberg/tree/master/packages/i18n/README.md",
+	"homepage": "https://github.com/WordPress/gutenberg/tree/HEAD/packages/i18n/README.md",
 	"repository": {
@@ -31,2 +31,3 @@ "type": "git",
 		"@babel/runtime": "^7.12.5",
+		"@wordpress/hooks": "^2.11.1-next.1+c95ee08bb",
 		"gettext-parser": "^1.3.1",
@@ -41,3 +42,3 @@ "lodash": "^4.17.19",
 	},
-	"gitHead": "eb424c9ed3dffb9ca4c31d7c81a3be85b0c94a74"
+	"gitHead": "c95ee08bb6159683e530e4f29c53430f17e98761"
 }

README.md

@@ -38,2 +38,3 @@ # Internationalization (i18n)
 -   _initialDomain_ `[string]`: Domain for which configuration applies.
+-   _hooks_ `[Hooks]`: Hooks implementation.
 
@@ -44,2 +45,36 @@ _Returns_
 
+<a name="defaultI18n" href="#defaultI18n">#</a> **defaultI18n**
+
+Default, singleton instance of `I18n`.
+
+<a name="getLocaleData" href="#getLocaleData">#</a> **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.
+
+<a name="hasTranslation" href="#hasTranslation">#</a> **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.
+
 <a name="isRTL" href="#isRTL">#</a> **isRTL**
@@ -90,2 +125,14 @@
 
+<a name="subscribe" href="#subscribe">#</a> **subscribe**
+
+Subscribes to changes of locale data
+
+_Parameters_
+
+-   _callback_ `SubscribeCallback`: Subscription callback
+
+_Returns_
+
+-   `UnsubscribeCallback`: Unsubscribe callback
+
 <a name="_n" href="#_n">#</a> **\_n**
@@ -92,0 +139,0 @@

src/create-i18n.js

@@ -25,5 +25,19 @@ /**
 
-/* eslint-disable jsdoc/valid-types */
+/*
+ * Regular expression that matches i18n hooks like `i18n.gettext`, `i18n.ngettext`,
+ * `i18n.gettext_domain` or `i18n.ngettext_with_context` or `i18n.has_translation`.
+ */
+const I18N_HOOK_REGEXP = /^i18n\.(n?gettext|has_translation)(_|$)/;
+
 /**
+ * @typedef {(domain?: string) => LocaleData} GetLocaleData
+ *
+ * Returns locale data by domain in a
+ * Jed-formatted JSON object shape.
+ *
+ * @see http://messageformat.github.io/Jed/
+ */
+/**
  * @typedef {(data?: LocaleData, domain?: string) => void} SetLocaleData
+ *
  * Merges locale data into the Tannin instance by domain. Accepts data in a
@@ -34,3 +48,14 @@ * Jed-formatted JSON object shape.
  */
+/** @typedef {() => void} SubscribeCallback */
+/** @typedef {() => void} UnsubscribeCallback */
 /**
+ * @typedef {(callback: SubscribeCallback) => UnsubscribeCallback} Subscribe
+ *
+ * Subscribes to changes of locale data
+ */
+/**
+ * @typedef {(domain?: string) => string} GetFilterDomain
+ * Retrieve the domain to use when calling domain-specific filters.
+ */
+/**
  * @typedef {(text: string, domain?: string) => string} __
@@ -75,3 +100,8 @@ *
  */
-/* eslint-enable jsdoc/valid-types */
+/**
+ * @typedef {(single: string, context?: string, domain?: string) => boolean} HasTranslation
+ *
+ * Check if there is a translation for a given string in singular form.
+ */
+/** @typedef {import('@wordpress/hooks').Hooks} Hooks */
 
@@ -82,4 +112,6 @@ /**
  * @typedef I18n
+ * @property {GetLocaleData} getLocaleData Returns locale data by domain in a Jed-formatted JSON object shape.
  * @property {SetLocaleData} setLocaleData Merges locale data into the Tannin instance by domain. Accepts data in a
  *                                         Jed-formatted JSON object shape.
+ * @property {Subscribe} subscribe         Subscribes to changes of Tannin locale data.
  * @property {__} __                       Retrieve the translation of text.
@@ -92,2 +124,3 @@ * @property {_x} _x                       Retrieve translated string with gettext context.
  * @property {IsRtl} isRTL                 Check if current locale is RTL.
+ * @property {HasTranslation} hasTranslation Check if there is a translation for a given string.
  */
@@ -100,5 +133,6 @@
  * @param {string}     [initialDomain]  Domain for which configuration applies.
+ * @param {Hooks} [hooks]     Hooks implementation.
  * @return {I18n}                       I18n instance
  */
-export const createI18n = ( initialData, initialDomain ) => {
+export const createI18n = ( initialData, initialDomain, hooks ) => {
 	/**
@@ -111,4 +145,27 @@ * The underlying instance of Tannin to which exported functions interface.
 
-	/** @type {SetLocaleData} */
-	const setLocaleData = ( data, domain = 'default' ) => {
+	const listeners = new Set();
+
+	const notifyListeners = () => {
+		listeners.forEach( ( listener ) => listener() );
+	};
+
+	/**
+	 * Subscribe to changes of locale data.
+	 *
+	 * @param {SubscribeCallback} callback Subscription callback.
+	 * @return {UnsubscribeCallback} Unsubscribe callback.
+	 */
+	const subscribe = ( callback ) => {
+		listeners.add( callback );
+		return () => listeners.delete( callback );
+	};
+
+	/** @type {GetLocaleData} */
+	const getLocaleData = ( domain = 'default' ) => tannin.data[ domain ];
+
+	/**
+	 * @param {LocaleData} [data]
+	 * @param {string} [domain]
+	 */
+	const doSetLocaleData = ( data, domain = 'default' ) => {
 		tannin.data[ domain ] = {
@@ -128,2 +185,8 @@ ...DEFAULT_LOCALE_DATA,
 
+	/** @type {SetLocaleData} */
+	const setLocaleData = ( data, domain ) => {
+		doSetLocaleData( data, domain );
+		notifyListeners();
+	};
+
 	/**
@@ -152,3 +215,4 @@ * Wrapper for Tannin's `dcnpgettext`. Populates default locale data if not
 		if ( ! tannin.data[ domain ] ) {
-			setLocaleData( undefined, domain );
+			// use `doSetLocaleData` to set silently, without notifying listeners
+			doSetLocaleData( undefined, domain );
 		}
@@ -159,5 +223,35 @@
 
+	/** @type {GetFilterDomain} */
+	const getFilterDomain = ( domain = 'default' ) => domain;
+
 	/** @type {__} */
 	const __ = ( text, domain ) => {
-		return dcnpgettext( domain, undefined, text );
+		let translation = dcnpgettext( domain, undefined, text );
+		if ( ! hooks ) {
+			return translation;
+		}
+
+		/**
+		 * Filters text with its translation.
+		 *
+		 * @param {string} translation Translated text.
+		 * @param {string} text        Text to translate.
+		 * @param {string} domain      Text domain. Unique identifier for retrieving translated strings.
+		 */
+		translation = /** @type {string} */ (
+			/** @type {*} */ hooks.applyFilters(
+				'i18n.gettext',
+				translation,
+				text,
+				domain
+			)
+		);
+		return /** @type {string} */ (
+			/** @type {*} */ hooks.applyFilters(
+				'i18n.gettext_' + getFilterDomain( domain ),
+				translation,
+				text,
+				domain
+			)
+		);
 	};
@@ -167,3 +261,33 @@
 	const _x = ( text, context, domain ) => {
-		return dcnpgettext( domain, context, text );
+		let translation = dcnpgettext( domain, context, text );
+		if ( ! hooks ) {
+			return translation;
+		}
+
+		/**
+		 * Filters text with its translation based on context information.
+		 *
+		 * @param {string} translation Translated text.
+		 * @param {string} text        Text to translate.
+		 * @param {string} context     Context information for the translators.
+		 * @param {string} domain      Text domain. Unique identifier for retrieving translated strings.
+		 */
+		translation = /** @type {string} */ (
+			/** @type {*} */ hooks.applyFilters(
+				'i18n.gettext_with_context',
+				translation,
+				text,
+				context,
+				domain
+			)
+		);
+		return /** @type {string} */ (
+			/** @type {*} */ hooks.applyFilters(
+				'i18n.gettext_with_context_' + getFilterDomain( domain ),
+				translation,
+				text,
+				context,
+				domain
+			)
+		);
 	};
@@ -173,3 +297,42 @@
 	const _n = ( single, plural, number, domain ) => {
-		return dcnpgettext( domain, undefined, single, plural, number );
+		let translation = dcnpgettext(
+			domain,
+			undefined,
+			single,
+			plural,
+			number
+		);
+		if ( ! hooks ) {
+			return translation;
+		}
+
+		/**
+		 * Filters the singular or plural form of a string.
+		 *
+		 * @param {string} translation Translated text.
+		 * @param {string} single      The text to be used if the number is singular.
+		 * @param {string} plural      The text to be used if the number is plural.
+		 * @param {string} number      The number to compare against to use either the singular or plural form.
+		 * @param {string} domain      Text domain. Unique identifier for retrieving translated strings.
+		 */
+		translation = /** @type {string} */ (
+			/** @type {*} */ hooks.applyFilters(
+				'i18n.ngettext',
+				translation,
+				single,
+				plural,
+				number,
+				domain
+			)
+		);
+		return /** @type {string} */ (
+			/** @type {*} */ hooks.applyFilters(
+				'i18n.ngettext_' + getFilterDomain( domain ),
+				translation,
+				single,
+				plural,
+				number,
+				domain
+			)
+		);
 	};
@@ -179,3 +342,46 @@
 	const _nx = ( single, plural, number, context, domain ) => {
-		return dcnpgettext( domain, context, single, plural, number );
+		let translation = dcnpgettext(
+			domain,
+			context,
+			single,
+			plural,
+			number
+		);
+		if ( ! hooks ) {
+			return translation;
+		}
+
+		/**
+		 * Filters the singular or plural form of a string with gettext context.
+		 *
+		 * @param {string} translation Translated text.
+		 * @param {string} single      The text to be used if the number is singular.
+		 * @param {string} plural      The text to be used if the number is plural.
+		 * @param {string} number      The number to compare against to use either the singular or plural form.
+		 * @param {string} context     Context information for the translators.
+		 * @param {string} domain      Text domain. Unique identifier for retrieving translated strings.
+		 */
+		translation = /** @type {string} */ (
+			/** @type {*} */ hooks.applyFilters(
+				'i18n.ngettext_with_context',
+				translation,
+				single,
+				plural,
+				number,
+				context,
+				domain
+			)
+		);
+
+		return /** @type {string} */ (
+			/** @type {*} */ hooks.applyFilters(
+				'i18n.ngettext_with_context_' + getFilterDomain( domain ),
+				translation,
+				single,
+				plural,
+				number,
+				context,
+				domain
+			)
+		);
 	};
@@ -188,2 +394,38 @@
 
+	/** @type {HasTranslation} */
+	const hasTranslation = ( single, context, domain ) => {
+		const key = context ? context + '\u0004' + single : single;
+		let result = !! tannin.data?.[ domain ?? 'default' ]?.[ key ];
+		if ( hooks ) {
+			/**
+			 * Filters the presence of a translation in the locale data.
+			 *
+			 * @param {boolean} hasTranslation Whether the translation is present or not..
+			 * @param {string} single The singular form of the translated text (used as key in locale data)
+			 * @param {string} context Context information for the translators.
+			 * @param {string} domain Text domain. Unique identifier for retrieving translated strings.
+			 */
+			result = /** @type { boolean } */ (
+				/** @type {*} */ hooks.applyFilters(
+					'i18n.has_translation',
+					result,
+					single,
+					context,
+					domain
+				)
+			);
+
+			result = /** @type { boolean } */ (
+				/** @type {*} */ hooks.applyFilters(
+					'i18n.has_translation_' + getFilterDomain( domain ),
+					result,
+					single,
+					context,
+					domain
+				)
+			);
+		}
+		return result;
+	};
+
 	if ( initialData ) {
@@ -193,4 +435,20 @@ setLocaleData( initialData, initialDomain );
 
+	if ( hooks ) {
+		/**
+		 * @param {string} hookName
+		 */
+		const onHookAddedOrRemoved = ( hookName ) => {
+			if ( I18N_HOOK_REGEXP.test( hookName ) ) {
+				notifyListeners();
+			}
+		};
+
+		hooks.addAction( 'hookAdded', 'core/i18n', onHookAddedOrRemoved );
+		hooks.addAction( 'hookRemoved', 'core/i18n', onHookAddedOrRemoved );
+	}
+
 	return {
+		getLocaleData,
 		setLocaleData,
+		subscribe,
 		__,
@@ -201,3 +459,4 @@ _x,
 		isRTL,
+		hasTranslation,
 	};
 };

src/default-i18n.js

@@ -6,4 +6,14 @@ /**
 
-const i18n = createI18n();
+/**
+ * WordPress dependencies
+ */
+import { defaultHooks } from '@wordpress/hooks';
 
+const i18n = createI18n( undefined, undefined, defaultHooks );
+
+/**
+ * Default, singleton instance of `I18n`.
+ */
+export default i18n;
+
 /*
@@ -16,5 +26,17 @@ * Comments in this file are duplicated from ./i18n due to
  * @typedef {import('./create-i18n').LocaleData} LocaleData
+ * @typedef {import('./create-i18n').SubscribeCallback} SubscribeCallback
+ * @typedef {import('./create-i18n').UnsubscribeCallback} UnsubscribeCallback
  */
 
 /**
+ * Returns locale data by domain in a Jed-formatted JSON object shape.
+ *
+ * @see http://messageformat.github.io/Jed/
+ *
+ * @param {string} [domain] Domain for which to get the data.
+ * @return {LocaleData} Locale data.
+ */
+export const getLocaleData = i18n.getLocaleData.bind( i18n );
+
+/**
  * Merges locale data into the Tannin instance by domain. Accepts data in a
@@ -31,2 +53,10 @@ * Jed-formatted JSON object shape.
 /**
+ * Subscribes to changes of locale data
+ *
+ * @param {SubscribeCallback} callback Subscription callback
+ * @return {UnsubscribeCallback} Unsubscribe callback
+ */
+export const subscribe = i18n.subscribe.bind( i18n );
+
+/**
  * Retrieve the translation of text.
@@ -100,1 +130,11 @@ *
 export const isRTL = i18n.isRTL.bind( i18n );
+
+/**
+ * Check if there is a translation for a given string (in singular form).
+ *
+ * @param {string} single Singular form of the string to look up.
+ * @param {string} [context] Context information for the translators.
+ * @param {string} [domain] Domain to retrieve the translated text.
+ * @return {boolean} Whether the translation exists or not.
+ */
+export const hasTranslation = i18n.hasTranslation.bind( i18n );

src/index.js

 export { sprintf } from './sprintf';
 export * from './create-i18n';
-export { setLocaleData, __, _x, _n, _nx, isRTL } from './default-i18n';
+export {
+	default as defaultI18n,
+	setLocaleData,
+	getLocaleData,
+	subscribe,
+	__,
+	_x,
+	_n,
+	_nx,
+	isRTL,
+	hasTranslation,
+} from './default-i18n';

src/test/create-i18n.js

 /* eslint-disable @wordpress/i18n-text-domain, @wordpress/i18n-translator-comments */
 
 /**
+ * WordPress dependencies
+ */
+import { createHooks } from '@wordpress/hooks';
+
+/**
  * Internal dependencies
@@ -194,2 +199,164 @@ */
 
+describe( 'i18n filters', () => {
+	function createHooksWithI18nFilters() {
+		const hooks = createHooks();
+		hooks.addFilter(
+			'i18n.gettext',
+			'test',
+			( translation ) => translation + '/i18n.gettext'
+		);
+		hooks.addFilter(
+			'i18n.gettext_default',
+			'test',
+			( translation ) => translation + '/i18n.gettext_default'
+		);
+		hooks.addFilter(
+			'i18n.gettext_domain',
+			'test',
+			( translation ) => translation + '/i18n.gettext_domain'
+		);
+
+		hooks.addFilter(
+			'i18n.ngettext',
+			'test',
+			( translation ) => translation + '/i18n.ngettext'
+		);
+		hooks.addFilter(
+			'i18n.ngettext_default',
+			'test',
+			( translation ) => translation + '/i18n.ngettext_default'
+		);
+		hooks.addFilter(
+			'i18n.ngettext_domain',
+			'test',
+			( translation ) => translation + '/i18n.ngettext_domain'
+		);
+
+		hooks.addFilter(
+			'i18n.gettext_with_context',
+			'test',
+			( translation, text, context ) =>
+				translation + `/i18n.gettext_with_${ context }`
+		);
+		hooks.addFilter(
+			'i18n.gettext_with_context_default',
+			'test',
+			( translation, text, context ) =>
+				translation + `/i18n.gettext_with_${ context }_default`
+		);
+		hooks.addFilter(
+			'i18n.gettext_with_context_domain',
+			'test',
+			( translation, text, context ) =>
+				translation + `/i18n.gettext_with_${ context }_domain`
+		);
+
+		hooks.addFilter(
+			'i18n.ngettext_with_context',
+			'test',
+			( translation, single, plural, number, context ) =>
+				translation + `/i18n.ngettext_with_${ context }`
+		);
+		hooks.addFilter(
+			'i18n.ngettext_with_context_default',
+			'test',
+			( translation, single, plural, number, context ) =>
+				translation + `/i18n.ngettext_with_${ context }_default`
+		);
+		hooks.addFilter(
+			'i18n.ngettext_with_context_domain',
+			'test',
+			( translation, single, plural, number, context ) =>
+				translation + `/i18n.ngettext_with_${ context }_domain`
+		);
+		hooks.addFilter(
+			'i18n.has_translation',
+			'test',
+			( hasTranslation, single, context, domain ) => {
+				if (
+					single === 'Always' &&
+					! context &&
+					( domain ?? 'default' ) === 'default'
+				) {
+					return true;
+				}
+
+				return hasTranslation;
+			}
+		);
+		return hooks;
+	}
+
+	test( '__() calls filters', () => {
+		const hooks = createHooksWithI18nFilters();
+		const i18n = createI18n( undefined, undefined, hooks );
+
+		expect( i18n.__( 'hello' ) ).toEqual(
+			'hello/i18n.gettext/i18n.gettext_default'
+		);
+		expect( i18n.__( 'hello', 'domain' ) ).toEqual(
+			'hello/i18n.gettext/i18n.gettext_domain'
+		);
+	} );
+
+	test( '_x() calls filters', () => {
+		const hooks = createHooksWithI18nFilters();
+		const i18n = createI18n( undefined, undefined, hooks );
+
+		expect( i18n._x( 'hello', 'ctx' ) ).toEqual(
+			'hello/i18n.gettext_with_ctx/i18n.gettext_with_ctx_default'
+		);
+		expect( i18n._x( 'hello', 'ctx', 'domain' ) ).toEqual(
+			'hello/i18n.gettext_with_ctx/i18n.gettext_with_ctx_domain'
+		);
+	} );
+
+	test( '_n() calls filters', () => {
+		const hooks = createHooksWithI18nFilters();
+		const i18n = createI18n( undefined, undefined, hooks );
+
+		expect( i18n._n( 'hello', 'hellos', 1 ) ).toEqual(
+			'hello/i18n.ngettext/i18n.ngettext_default'
+		);
+		expect( i18n._n( 'hello', 'hellos', 1, 'domain' ) ).toEqual(
+			'hello/i18n.ngettext/i18n.ngettext_domain'
+		);
+		expect( i18n._n( 'hello', 'hellos', 2 ) ).toEqual(
+			'hellos/i18n.ngettext/i18n.ngettext_default'
+		);
+		expect( i18n._n( 'hello', 'hellos', 2, 'domain' ) ).toEqual(
+			'hellos/i18n.ngettext/i18n.ngettext_domain'
+		);
+	} );
+
+	test( '_nx() calls filters', () => {
+		const hooks = createHooksWithI18nFilters();
+		const i18n = createI18n( undefined, undefined, hooks );
+
+		expect( i18n._nx( 'hello', 'hellos', 1, 'ctx' ) ).toEqual(
+			'hello/i18n.ngettext_with_ctx/i18n.ngettext_with_ctx_default'
+		);
+		expect( i18n._nx( 'hello', 'hellos', 1, 'ctx', 'domain' ) ).toEqual(
+			'hello/i18n.ngettext_with_ctx/i18n.ngettext_with_ctx_domain'
+		);
+		expect( i18n._nx( 'hello', 'hellos', 2, 'ctx' ) ).toEqual(
+			'hellos/i18n.ngettext_with_ctx/i18n.ngettext_with_ctx_default'
+		);
+		expect( i18n._nx( 'hello', 'hellos', 2, 'ctx', 'domain' ) ).toEqual(
+			'hellos/i18n.ngettext_with_ctx/i18n.ngettext_with_ctx_domain'
+		);
+	} );
+
+	test( 'hasTranslation() calls filters', () => {
+		const hooks = createHooksWithI18nFilters();
+		const { hasTranslation } = createI18n( frenchLocale, undefined, hooks );
+
+		expect( hasTranslation( 'hello' ) ).toBe( true );
+		expect( hasTranslation( 'hello', 'not a greeting' ) ).toBe( false );
+		expect( hasTranslation( 'Always' ) ).toBe( true );
+		expect( hasTranslation( 'Always', 'other context' ) ).toBe( false );
+		expect( hasTranslation( 'Always', undefined, 'domain' ) ).toBe( false );
+	} );
+} );
+
 /* eslint-enable @wordpress/i18n-text-domain, @wordpress/i18n-translator-comments */

tsconfig.json

@@ -7,3 +7,6 @@ {
 	},
-	"include": [ "src/**/*" ]
+	"references": [
+		{ "path": "../hooks" },
+	],
+  	"include": [ "src/**/*" ],
 }

New alerts

Manifest confusion

Supply chain risk

This package has inconsistent metadata. This could be malicious or caused by an error when publishing the package.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

200953

increased by55.5%

Number of package files

40

increased by5.26%

Lines of code

2527

increased by73.56%

Number of lines in readme file

215

increased by27.98%

Worsened metrics

Dependency count

7

increased by16.67%

Number of medium supply chain risk alerts

1

increased byInfinity%

Dependency changes

• + Added@wordpress/hooks@^2.11.1-next.1+c95ee08bb

• + Added@wordpress/hooks@2.12.3(transitive)