@wordpress/i18n 5.26.0 → 6.0.1-next.46f643fa0.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/i18n",
-	"version": "5.26.0",
+	"version": "6.0.1-next.46f643fa0.0",
 	"description": "WordPress internationalization (i18n) library.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -32,14 +32,14 @@
 	},
 	"dependencies": {
 		"@babel/runtime": "7.25.7",
-		"@wordpress/hooks": "^4.26.0",
+		"@tannin/sprintf": "^1.3.1",
+		"@wordpress/hooks": "^4.27.1-next.46f643fa0.0",
 		"gettext-parser": "^1.3.1",
 		"memize": "^2.1.0",
-		"sprintf-js": "^1.1.1",
 		"tannin": "^1.2.0"
 	},
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "35e26942820d8237771af0c58e45b4303f0497f1"
+	"gitHead": "17e600e091675c5e3d809adfea23ac456bbeae19"
 }

package/src/create-i18n.ts

@@ -0,0 +1,405 @@
+/**
+ * External dependencies
+ */
+import type { TanninLocaleDomain } from 'tannin';
+import Tannin from 'tannin';
+/**
+ * Internal dependencies
+ */
+import type {
+	getFilterDomain,
+	I18n,
+	LocaleData,
+	SubscribeCallback,
+	TranslatableText,
+	UnsubscribeCallback,
+} from './types';
+/**
+ * WordPress dependencies
+ */
+import type { Hooks } from '@wordpress/hooks';
+/**
+ * Default locale data to use for Tannin domain when not otherwise provided.
+ * Assumes an English plural forms expression.
+ */
+const DEFAULT_LOCALE_DATA: LocaleData = {
+	'': {
+		plural_forms( n: number ) {
+			return n === 1 ? 0 : 1;
+		},
+	},
+};
+
+/*
+ * 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)(_|$)/;
+
+/**
+ * Create an i18n instance
+ *
+ * @param [initialData]   Locale data configuration.
+ * @param [initialDomain] Domain for which configuration applies.
+ * @param [hooks]         Hooks implementation.
+ *
+ * @return I18n instance.
+ */
+export const createI18n = < TextDomain extends string >(
+	initialData?: LocaleData< TextDomain >,
+	initialDomain?: TextDomain,
+	hooks?: Hooks
+): I18n< TextDomain > => {
+	/**
+	 * The underlying instance of Tannin to which exported functions interface.
+	 */
+	const tannin = new Tannin( {} );
+
+	const listeners = new Set< () => void >();
+
+	const notifyListeners = () => {
+		listeners.forEach( ( listener ) => listener() );
+	};
+
+	/**
+	 * Subscribe to changes of locale data.
+	 *
+	 * @param callback Subscription callback.
+	 * @return Unsubscribe callback.
+	 */
+	const subscribe = ( callback: SubscribeCallback ): UnsubscribeCallback => {
+		listeners.add( callback );
+		return () => listeners.delete( callback );
+	};
+
+	const getLocaleData: I18n< TextDomain >[ 'getLocaleData' ] = (
+		domain = 'default' as TextDomain
+	) => tannin.data[ domain ] as LocaleData< TextDomain >;
+
+	/**
+	 * @param [data]
+	 * @param [domain]
+	 */
+	const doSetLocaleData = (
+		data?: LocaleData,
+		domain: TextDomain = 'default' as TextDomain
+	) => {
+		tannin.data[ domain ] = {
+			...tannin.data[ domain ],
+			...data,
+		} as TanninLocaleDomain;
+
+		// Populate default domain configuration (supported locale date which omits
+		// a plural forms expression).
+		tannin.data[ domain ][ '' ] = {
+			...DEFAULT_LOCALE_DATA[ '' ],
+			...tannin.data[ domain ]?.[ '' ],
+		};
+
+		// Clean up cached plural forms functions cache as it might be updated.
+		delete tannin.pluralForms[ domain ];
+	};
+
+	const setLocaleData: I18n< TextDomain >[ 'setLocaleData' ] = (
+		data,
+		domain
+	) => {
+		doSetLocaleData( data, domain );
+		notifyListeners();
+	};
+
+	const addLocaleData: I18n< TextDomain >[ 'addLocaleData' ] = (
+		data,
+		domain = 'default' as TextDomain
+	) => {
+		tannin.data[ domain ] = {
+			...tannin.data[ domain ],
+			...data,
+			// Populate default domain configuration (supported locale date which omits
+			// a plural forms expression).
+			'': {
+				...DEFAULT_LOCALE_DATA[ '' ],
+				...tannin.data[ domain ]?.[ '' ],
+				...data?.[ '' ],
+			},
+		} as TanninLocaleDomain;
+
+		// Clean up cached plural forms functions cache as it might be updated.
+		delete tannin.pluralForms[ domain ];
+
+		notifyListeners();
+	};
+
+	const resetLocaleData: I18n< TextDomain >[ 'resetLocaleData' ] = (
+		data,
+		domain
+	) => {
+		// Reset all current Tannin locale data.
+		tannin.data = {};
+
+		// Reset cached plural forms functions cache.
+		tannin.pluralForms = {};
+
+		setLocaleData( data, domain );
+	};
+
+	/**
+	 * Wrapper for Tannin's `dcnpgettext`. Populates default locale data if not
+	 * otherwise previously assigned.
+	 *
+	 * @param domain   Domain to retrieve the translated text.
+	 * @param context  Context information for the translators.
+	 * @param single   Text to translate if non-plural. Used as
+	 *                 fallback return value on a caught error.
+	 * @param [plural] The text to be used if the number is
+	 *                 plural.
+	 * @param [number] The number to compare against to use
+	 *                 either the singular or plural form.
+	 *
+	 * @return The translated string.
+	 */
+	const dcnpgettext = (
+		domain = 'default' as TextDomain,
+		context: string | void,
+		single: string,
+		plural?: string,
+		number?: number
+	): string => {
+		if ( ! tannin.data[ domain ] ) {
+			// Use `doSetLocaleData` to set silently, without notifying listeners.
+			doSetLocaleData( undefined, domain );
+		}
+
+		return tannin.dcnpgettext( domain, context, single, plural, number );
+	};
+
+	const getFilterDomain: getFilterDomain = ( domain ) => domain || 'default';
+
+	const __: I18n< TextDomain >[ '__' ] = ( text, domain ) => {
+		let translation = dcnpgettext( domain, undefined, text );
+		if ( ! hooks ) {
+			return translation as TranslatableText< typeof text >;
+		}
+
+		/**
+		 * Filters text with its translation.
+		 *
+		 * @param translation Translated text.
+		 * @param text        Text to translate.
+		 * @param domain      Text domain. Unique identifier for retrieving translated strings.
+		 */
+		translation = hooks.applyFilters(
+			'i18n.gettext',
+			translation,
+			text,
+			domain
+		) as TranslatableText< typeof text >;
+
+		return hooks.applyFilters(
+			'i18n.gettext_' + getFilterDomain( domain ),
+			translation,
+			text,
+			domain
+		) as TranslatableText< typeof text >;
+	};
+
+	const _x: I18n< TextDomain >[ '_x' ] = ( text, context, domain ) => {
+		let translation = dcnpgettext( domain, context, text );
+		if ( ! hooks ) {
+			return translation as TranslatableText< typeof text >;
+		}
+
+		/**
+		 * Filters text with its translation based on context information.
+		 *
+		 * @param translation Translated text.
+		 * @param text        Text to translate.
+		 * @param context     Context information for the translators.
+		 * @param domain      Text domain. Unique identifier for retrieving translated strings.
+		 */
+		translation = hooks.applyFilters(
+			'i18n.gettext_with_context',
+			translation,
+			text,
+			context,
+			domain
+		) as TranslatableText< typeof text >;
+
+		return hooks.applyFilters(
+			'i18n.gettext_with_context_' + getFilterDomain( domain ),
+			translation,
+			text,
+			context,
+			domain
+		) as TranslatableText< typeof text >;
+	};
+
+	const _n: I18n< TextDomain >[ '_n' ] = (
+		single,
+		plural,
+		number,
+		domain
+	) => {
+		let translation = dcnpgettext(
+			domain,
+			undefined,
+			single,
+			plural,
+			number
+		);
+		if ( ! hooks ) {
+			return translation as TranslatableText<
+				typeof single | typeof plural
+			>;
+		}
+
+		/**
+		 * Filters the singular or plural form of a string.
+		 *
+		 * @param translation Translated text.
+		 * @param single      The text to be used if the number is singular.
+		 * @param plural      The text to be used if the number is plural.
+		 * @param number      The number to compare against to use either the singular or plural form.
+		 * @param domain      Text domain. Unique identifier for retrieving translated strings.
+		 */
+		translation = hooks.applyFilters(
+			'i18n.ngettext',
+			translation,
+			single,
+			plural,
+			number,
+			domain
+		) as TranslatableText< typeof single | typeof plural >;
+
+		return hooks.applyFilters(
+			'i18n.ngettext_' + getFilterDomain( domain ),
+			translation,
+			single,
+			plural,
+			number,
+			domain
+		) as TranslatableText< typeof single | typeof plural >;
+	};
+
+	const _nx: I18n< TextDomain >[ '_nx' ] = (
+		single,
+		plural,
+		number,
+		context,
+		domain
+	) => {
+		let translation = dcnpgettext(
+			domain,
+			context,
+			single,
+			plural,
+			number
+		);
+		if ( ! hooks ) {
+			return translation as TranslatableText<
+				typeof single | typeof plural
+			>;
+		}
+
+		/**
+		 * Filters the singular or plural form of a string with gettext context.
+		 *
+		 * @param translation Translated text.
+		 * @param single      The text to be used if the number is singular.
+		 * @param plural      The text to be used if the number is plural.
+		 * @param number      The number to compare against to use either the singular or plural form.
+		 * @param context     Context information for the translators.
+		 * @param domain      Text domain. Unique identifier for retrieving translated strings.
+		 */
+		translation = hooks.applyFilters(
+			'i18n.ngettext_with_context',
+			translation,
+			single,
+			plural,
+			number,
+			context,
+			domain
+		) as TranslatableText< typeof single | typeof plural >;
+
+		return hooks.applyFilters(
+			'i18n.ngettext_with_context_' + getFilterDomain( domain ),
+			translation,
+			single,
+			plural,
+			number,
+			context,
+			domain
+		) as TranslatableText< typeof single | typeof plural >;
+	};
+
+	const isRTL: I18n< TextDomain >[ 'isRTL' ] = () => {
+		return 'rtl' === _x( 'ltr', 'text direction' );
+	};
+
+	const hasTranslation: I18n< TextDomain >[ '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 hasTranslation Whether the translation is present or not..
+			 * @param single         The singular form of the translated text (used as key in locale data)
+			 * @param context        Context information for the translators.
+			 * @param domain         Text domain. Unique identifier for retrieving translated strings.
+			 */
+			result = hooks.applyFilters(
+				'i18n.has_translation',
+				result,
+				single,
+				context,
+				domain
+			) as boolean;
+
+			result = hooks.applyFilters(
+				'i18n.has_translation_' + getFilterDomain( domain ),
+				result,
+				single,
+				context,
+				domain
+			) as boolean;
+		}
+		return result;
+	};
+
+	if ( initialData ) {
+		setLocaleData( initialData, initialDomain );
+	}
+
+	if ( hooks ) {
+		/**
+		 * @param hookName
+		 */
+		const onHookAddedOrRemoved = ( hookName: string ) => {
+			if ( I18N_HOOK_REGEXP.test( hookName ) ) {
+				notifyListeners();
+			}
+		};
+
+		hooks.addAction( 'hookAdded', 'core/i18n', onHookAddedOrRemoved );
+		hooks.addAction( 'hookRemoved', 'core/i18n', onHookAddedOrRemoved );
+	}
+
+	return {
+		getLocaleData,
+		setLocaleData,
+		addLocaleData,
+		resetLocaleData,
+		subscribe,
+		__,
+		_x,
+		_n,
+		_nx,
+		isRTL,
+		hasTranslation,
+	};
+};

package/src/{default-i18n.js → default-i18n.ts}

@@ -7,6 +7,12 @@ import { createI18n } from './create-i18n';
  * WordPress dependencies
  */
 import { defaultHooks } from '@wordpress/hooks';
+import {
+	LocaleData,
+	SubscribeCallback,
+	TranslatableText,
+	UnsubscribeCallback,
+} from './types';
 
 const i18n = createI18n( undefined, undefined, defaultHooks );
 
@@ -20,19 +26,13 @@ export default i18n;
  * https://github.com/WordPress/gutenberg/pull/20318#issuecomment-590837722
  */
 
-/**
- * @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.
+ * @param { string | undefined } [domain] Domain for which to get the data.
+ * @return { LocaleData } Locale data.
  */
 export const getLocaleData = i18n.getLocaleData.bind( i18n );
 
@@ -42,8 +42,8 @@ export const getLocaleData = i18n.getLocaleData.bind( i18n );
  *
  * @see http://messageformat.github.io/Jed/
  *
- * @param {LocaleData} [data]   Locale data configuration.
- * @param {string}     [domain] Domain for which configuration applies.
+ * @param {LocaleData }        [data]   Locale data configuration.
+ * @param {string | undefined} [domain] Domain for which configuration applies.
  */
 export const setLocaleData = i18n.setLocaleData.bind( i18n );
 
@@ -53,8 +53,8 @@ export const setLocaleData = i18n.setLocaleData.bind( i18n );
  *
  * @see http://messageformat.github.io/Jed/
  *
- * @param {LocaleData} [data]   Locale data configuration.
- * @param {string}     [domain] Domain for which configuration applies.
+ * @param {LocaleData}         [data]   Locale data configuration.
+ * @param {string | undefined} [domain] Domain for which configuration applies.
  */
 export const resetLocaleData = i18n.resetLocaleData.bind( i18n );
 
@@ -71,10 +71,12 @@ export const subscribe = i18n.subscribe.bind( i18n );
  *
  * @see https://developer.wordpress.org/reference/functions/__/
  *
- * @param {string} text     Text to translate.
- * @param {string} [domain] Domain to retrieve the translated text.
+ * @template {string} Text
+ *
+ * @param {Text}               text   Text to translate.
+ * @param {string | undefined} domain Domain to retrieve the translated text.
  *
- * @return {string} Translated text.
+ * @return {TranslatableText<Text>} Translated text.
  */
 export const __ = i18n.__.bind( i18n );
 
@@ -83,11 +85,13 @@ export const __ = i18n.__.bind( i18n );
  *
  * @see https://developer.wordpress.org/reference/functions/_x/
  *
- * @param {string} text     Text to translate.
- * @param {string} context  Context information for the translators.
- * @param {string} [domain] Domain to retrieve the translated text.
+ * @template {string} Text
  *
- * @return {string} Translated context string without pipe.
+ * @param {Text}               text    Text to translate.
+ * @param {string}             context Context information for the translators.
+ * @param {string | undefined} domain  Domain to retrieve the translated text.
+ *
+ * @return {TranslatableText<Text>} Translated context string without pipe.
  */
 export const _x = i18n._x.bind( i18n );
 
@@ -97,13 +101,16 @@ export const _x = i18n._x.bind( i18n );
  *
  * @see https://developer.wordpress.org/reference/functions/_n/
  *
- * @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 {number} number   The number to compare against to use either the
- *                          singular or plural form.
- * @param {string} [domain] Domain to retrieve the translated text.
+ * @template {string} Single
+ * @template {string} Plural
+ *
+ * @param {Single}             single The text to be used if the number is singular.
+ * @param {Plural}             plural The text to be used if the number is plural.
+ * @param {number}             number The number to compare against to use either the
+ *                                    singular or plural form.
+ * @param {string | undefined} domain Domain to retrieve the translated text.
  *
- * @return {string} The translated singular or plural form.
+ * @return {TranslatableText<Single | Plural>} The translated singular or plural form.
  */
 export const _n = i18n._n.bind( i18n );
 
@@ -113,14 +120,18 @@ export const _n = i18n._n.bind( i18n );
  *
  * @see https://developer.wordpress.org/reference/functions/_nx/
  *
- * @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 {number} 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] Domain to retrieve the translated text.
+ * @template {string} Single
+ * @template {string} Plural
+ * @param {Single}             single   The text to be used if the number is singular.
  *
- * @return {string} The translated singular or plural form.
+ * @param {Single}             single   The text to be used if the number is singular.
+ * @param {Plural}             plural   The text to be used if the number is plural.
+ * @param {number}             number   The number to compare against to use either the
+ *                                      singular or plural form.
+ * @param {string}             context  Context information for the translators.
+ * @param {string | undefined} [domain] Domain to retrieve the translated text.
+ *
+ * @return {TranslatableText<Single | Plural>} The translated singular or plural form.
  */
 export const _nx = i18n._nx.bind( i18n );
 
@@ -139,9 +150,10 @@ 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.
+ * @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 );

package/src/index.ts

@@ -0,0 +1,16 @@
+export { sprintf } from './sprintf';
+export * from './create-i18n';
+export type * from './types';
+export {
+	default as defaultI18n,
+	setLocaleData,
+	resetLocaleData,
+	getLocaleData,
+	subscribe,
+	__,
+	_x,
+	_n,
+	_nx,
+	isRTL,
+	hasTranslation,
+} from './default-i18n';

package/src/sprintf.ts

@@ -0,0 +1,37 @@
+/**
+ * External dependencies
+ */
+// Disable reason: `eslint-plugin-import` doesn't support `exports` (https://github.com/import-js/eslint-plugin-import/issues/1810)
+// eslint-disable-next-line import/no-unresolved
+import _sprintf from '@tannin/sprintf';
+
+/**
+ * Internal dependencies
+ */
+import type { DistributeSprintfArgs, TranslatableText } from './types';
+
+export function sprintf< T extends string >(
+	format: T | TranslatableText< T >,
+	...args: DistributeSprintfArgs< T >
+): string;
+export function sprintf< T extends string >(
+	format: T | TranslatableText< T >,
+	args: DistributeSprintfArgs< T >
+): string;
+
+/**
+ * Returns a formatted string.
+ *
+ * @param format The format of the string to generate.
+ * @param args   Arguments to apply to the format.
+ *
+ * @see https://www.npmjs.com/package/@tannin/sprintf
+ *
+ * @return The formatted string.
+ */
+export function sprintf< T extends string >(
+	format: T | TranslatableText< T >,
+	...args: DistributeSprintfArgs< T >
+): string {
+	return _sprintf( format as T, ...( args as DistributeSprintfArgs< T > ) );
+}