I18N: Add translation support for script modules.

Add automatic translation loading for script modules (ES modules), so strings using `__()` and friends from `@wordpress/i18n` can be translated at runtime. This brings classic script i18n parity to script modules registered via `wp_register_script_module()`, which previously had no way to load translation data, leaving strings untranslated on screens like Connectors and Fonts that are built as script modules.

At the `admin_print_footer_scripts` and `wp_footer` actions, every enqueued script module and its dependencies are walked, the translation chunk is loaded for each, and an inline `<script>` calls `wp.i18n.setLocaleData()` so translations are available before deferred modules execute. Note there is currently a runtime dependency on the `wp-i18n` classic script, which is printed just-in-time if not already enqueued. This coupling is to be removed in a future release.

Public API:

* `WP_Script_Modules::set_translations()` stores the text domain (and optional path) per registered module to override the text domain and path. A global `wp_set_script_module_translations()` function is added as a wrapper around `wp_script_modules()->set_translations()`.
* `WP_Script_Modules::get_registered()` obtains a registered module's data. See #60597.
* `WP_Script_Modules::print_script_module_translations()` emits inline `wp.i18n.setLocaleData()` calls after classic scripts load but before modules execute.
* `load_script_module_textdomain()` loads the translation data for a given script module ID and text domain.
* The existing `load_script_textdomain_relative_path` filter gains a third `$is_module` parameter so callers can distinguish classic-script and script-module lookups when resolving translation paths.

PHPStan types are also added in `WP_Script_Modules`. See #64238.

Developed in #11543

Props manzoorwanijk, westonruter, jsnajdr, jonsurrell, mukesh27, peterwilsoncc, 369work, desrosj, sabernhardt, nilambar, jorgefilipecosta, malayladu.
See #64238, #60597.
Fixes #65015.


git-svn-id: https://develop.svn.wordpress.org/trunk@62278 602fd350-edb4-49c9-b593-d223f7449a82

Author: westonruter

src/wp-includes/class-wp-script-modules.php

@@ -12,13 +12,24 @@
  * Core class used to register script modules.
  *
  * @since 6.5.0
+ *
+ * @phpstan-type ScriptModule array{
+ *     src: string,
+ *     version: string|false|null,
+ *     dependencies: array<int, array{ id: string, import: 'static'|'dynamic' }>,
+ *     in_footer: bool,
+ *     fetchpriority: 'auto'|'low'|'high',
+ *     textdomain?: string,
+ *     translations_path?: string,
+ * }
  */
 class WP_Script_Modules {
 	/**
 	 * Holds the registered script modules, keyed by script module identifier.
 	 *
 	 * @since 6.5.0
 	 * @var array<string, array<string, mixed>>
+	 * @phpstan-var array<string, ScriptModule>
 	 */
 	private $registered = array();
 
@@ -328,6 +339,87 @@ public function deregister( string $id ) {
 		unset( $this->registered[ $id ] );
 	}
 
+	/**
+	 * Overrides the text domain and path used to load translations for a script module.
+	 *
+	 * This is only needed for modules whose text domain differs from 'default'
+	 * or whose translation files live outside the standard locations, for
+	 * example plugin modules that register their own text domain. Translations
+	 * for modules that use the default domain are loaded automatically by
+	 * {@see WP_Script_Modules::print_script_module_translations()}.
+	 *
+	 * @since 7.0.0
+	 *
+	 * @param string $id     The identifier of the script module.
+	 * @param string $domain Optional. Text domain. Default 'default'.
+	 * @param string $path   Optional. The full file path to the directory containing translation files.
+	 * @return bool True if the text domain was registered, false if the module is not registered.
+	 */
+	public function set_translations( string $id, string $domain = 'default', string $path = '' ): bool {
+		if ( ! isset( $this->registered[ $id ] ) ) {
+			return false;
+		}
+
+		$this->registered[ $id ]['textdomain']        = $domain;
+		$this->registered[ $id ]['translations_path'] = $path;
+
+		return true;
+	}
+
+	/**
+	 * Prints translations for all enqueued script modules.
+	 *
+	 * Outputs inline `<script>` tags that call `wp.i18n.setLocaleData()` with
+	 * the translated strings for each script module. This must run before
+	 * the script modules execute.
+	 *
+	 * Auto-detects the text domain and translation path for each module from
+	 * its source URL. Modules whose text domain or path differs from the
+	 * defaults can opt into a specific domain/path via
+	 * {@see WP_Script_Modules::set_translations()}.
+	 *
+	 * @since 7.0.0
+	 */
+	public function print_script_module_translations(): void {
+		// Collect all module IDs that will be on the page (enqueued + their dependencies).
+		$module_ids = $this->get_sorted_dependencies( $this->queue );
+
+		$set_locale_data_js_function = <<<'JS'
+		( domain, translations ) => {
+			const localeData = translations.locale_data[ domain ] || translations.locale_data.messages;
+			localeData[""].domain = domain;
+			wp.i18n.setLocaleData( localeData, domain );
+		}
+		JS;
+
+		foreach ( $module_ids as $id ) {
+			$domain = $this->registered[ $id ]['textdomain'] ?? 'default';
+			$path   = $this->registered[ $id ]['translations_path'] ?? '';
+
+			$json_translations = load_script_module_textdomain( $id, $domain, $path );
+
+			if ( ! $json_translations ) {
+				continue;
+			}
+
+			$output    = sprintf(
+				'( %s )( %s, %s );',
+				$set_locale_data_js_function,
+				wp_json_encode( $domain, JSON_HEX_TAG | JSON_UNESCAPED_SLASHES ),
+				$json_translations
+			);
+			$script_id = "wp-script-module-translation-data-{$id}";
+			$output   .= "\n//# sourceURL=" . rawurlencode( $script_id );
+
+			// Ensure wp-i18n is printed; the inline script below relies on wp.i18n.setLocaleData().
+			if ( ! wp_script_is( 'wp-i18n', 'done' ) ) {
+				wp_scripts()->do_items( array( 'wp-i18n' ) );
+			}
+
+			wp_print_inline_script_tag( $output, array( 'id' => $script_id ) );
+		}
+	}
+
 	/**
 	 * Adds the hooks to print the import map, enqueued script modules and script
 	 * module preloads.
@@ -359,6 +451,15 @@ public function add_hooks() {
 		add_action( 'admin_print_footer_scripts', array( $this, 'print_enqueued_script_modules' ) );
 		add_action( 'admin_print_footer_scripts', array( $this, 'print_script_module_preloads' ) );
 
+		/*
+		 * Print translations after classic scripts like wp-i18n are loaded (at
+		 * priority 10 via _wp_footer_scripts), but before the script modules
+		 * execute. Script modules with type="module" are deferred by default,
+		 * so inline translation scripts at priority 11 will execute before them.
+		 */
+		add_action( 'wp_footer', array( $this, 'print_script_module_translations' ), 21 );
+		add_action( 'admin_print_footer_scripts', array( $this, 'print_script_module_translations' ), 11 );
+
 		add_action( 'wp_footer', array( $this, 'print_script_module_data' ) );
 		add_action( 'admin_print_footer_scripts', array( $this, 'print_script_module_data' ) );
 		add_action( 'wp_footer', array( $this, 'print_a11y_script_module_html' ), 20 );
@@ -631,6 +732,7 @@ private function get_import_map(): array {
 	 * @since 6.5.0
 	 *
 	 * @return array<string, array<string, mixed>> Script modules marked for enqueue, keyed by script module identifier.
+	 * @phpstan-return array<string, ScriptModule>
 	 */
 	private function get_marked_for_enqueue(): array {
 		return wp_array_slice_assoc(
@@ -652,6 +754,7 @@ private function get_marked_for_enqueue(): array {
 	 * @param string[] $import_types Optional. Import types of dependencies to retrieve: 'static', 'dynamic', or both.
 	 *                                         Default is both.
 	 * @return array<string, array<string, mixed>> List of dependencies, keyed by script module identifier.
+	 * @phpstan-return array<string, ScriptModule>
 	 */
 	private function get_dependencies( array $ids, array $import_types = array( 'static', 'dynamic' ) ): array {
 		$all_dependencies = array();
@@ -840,6 +943,19 @@ private function sort_item_dependencies( string $id, array $import_types, array
 		return true;
 	}
 
+	/**
+	 * Gets the data for a registered script module.
+	 *
+	 * @since 7.0.0
+	 *
+	 * @param string $id The script module identifier.
+	 * @return array|null The script module data, or null if not registered.
+	 * @phpstan-return ScriptModule|null
+	 */
+	public function get_registered( string $id ): ?array {
+		return $this->registered[ $id ] ?? null;
+	}
+
 	/**
 	 * Gets the versioned URL for a script module src.
 	 *

src/wp-includes/l10n.php

@@ -1134,24 +1134,80 @@ function load_child_theme_textdomain( $domain, $path = false ) {
  *
  * @see WP_Scripts::set_translations()
  *
- * @global WP_Textdomain_Registry $wp_textdomain_registry WordPress Textdomain Registry.
- *
  * @param string $handle Name of the script to register a translation domain to.
  * @param string $domain Optional. Text domain. Default 'default'.
  * @param string $path   Optional. The full file path to the directory containing translation files.
  * @return string|false The translated strings in JSON encoding on success,
  *                      false if the script textdomain could not be loaded.
  */
 function load_script_textdomain( $handle, $domain = 'default', $path = '' ) {
-	/** @var WP_Textdomain_Registry $wp_textdomain_registry */
-	global $wp_textdomain_registry;
-
 	$wp_scripts = wp_scripts();
 
 	if ( ! isset( $wp_scripts->registered[ $handle ] ) ) {
 		return false;
 	}
 
+	$src = $wp_scripts->registered[ $handle ]->src;
+
+	if ( ! preg_match( '|^(https?:)?//|', $src ) && ! ( $wp_scripts->content_url && str_starts_with( $src, $wp_scripts->content_url ) ) ) {
+		$src = $wp_scripts->base_url . $src;
+	}
+
+	return _load_script_textdomain_from_src( $handle, $src, $domain, $path, false );
+}
+
+/**
+ * Loads the translation data for a given script module ID and text domain.
+ *
+ * Works like {@see load_script_textdomain()} but for script modules registered
+ * via {@see wp_register_script_module()}.
+ *
+ * @since 7.0.0
+ *
+ * @param string $id     The script module identifier.
+ * @param string $domain Optional. Text domain. Default 'default'.
+ * @param string $path   Optional. The full file path to the directory containing translation files.
+ * @return string|false The JSON-encoded translated strings for the given script module and text domain.
+ *                      False if there are none.
+ */
+function load_script_module_textdomain( string $id, string $domain = 'default', string $path = '' ) {
+	$module = wp_script_modules()->get_registered( $id );
+	if ( null === $module ) {
+		return false;
+	}
+	$src = $module['src'];
+
+	// Ensure src is an absolute URL for path resolution.
+	if ( ! preg_match( '|^(https?:)?//|', $src ) ) {
+		$src = site_url( $src );
+	}
+
+	return _load_script_textdomain_from_src( $id, $src, $domain, $path, true );
+}
+
+/**
+ * Resolves and loads the translation JSON file for a given script or script module source URL.
+ *
+ * This is a shared implementation used by {@see load_script_textdomain()} and
+ * {@see load_script_module_textdomain()} to avoid duplicating the path
+ * resolution and file lookup logic.
+ *
+ * @since 7.0.0
+ * @access private
+ *
+ * @global WP_Textdomain_Registry $wp_textdomain_registry WordPress Textdomain Registry.
+ *
+ * @param string $handle    Name of the script or script module identifier to register a translation domain to.
+ * @param string $src       Absolute source URL of the script or script module.
+ * @param string $domain    Text domain.
+ * @param string $path      The full file path to the directory containing translation files,
+ *                          or an empty string to use the default path from the text domain registry.
+ * @param bool   $is_module Whether the source belongs to a script module (true) or a classic script (false).
+ * @return string|false The JSON-encoded translated strings on success, false otherwise.
+ */
+function _load_script_textdomain_from_src( string $handle, string $src, string $domain, string $path, bool $is_module ) {
+	global $wp_textdomain_registry;
+
 	$locale = determine_locale();
 
 	if ( ! $path ) {
@@ -1172,12 +1228,6 @@ function load_script_textdomain( $handle, $domain = 'default', $path = '' ) {
 		}
 	}
 
-	$src = $wp_scripts->registered[ $handle ]->src;
-
-	if ( ! preg_match( '|^(https?:)?//|', $src ) && ! ( $wp_scripts->content_url && str_starts_with( $src, $wp_scripts->content_url ) ) ) {
-		$src = $wp_scripts->base_url . $src;
-	}
-
 	$relative       = false;
 	$languages_path = WP_LANG_DIR;
 
@@ -1245,11 +1295,13 @@ function load_script_textdomain( $handle, $domain = 'default', $path = '' ) {
 	 * Filters the relative path of scripts used for finding translation files.
 	 *
 	 * @since 5.0.2
+	 * @since 7.0.0 The `$is_module` parameter was added.
 	 *
-	 * @param string|false $relative The relative path of the script. False if it could not be determined.
-	 * @param string       $src      The full source URL of the script.
+	 * @param string|false $relative  The relative path of the script. False if it could not be determined.
+	 * @param string       $src       The full source URL of the script.
+	 * @param bool         $is_module Whether the source belongs to a script module (true) or a classic script (false).
 	 */
-	$relative = apply_filters( 'load_script_textdomain_relative_path', $relative, $src );
+	$relative = apply_filters( 'load_script_textdomain_relative_path', $relative, $src, $is_module );
 
 	// If the source is not from WP.
 	if ( false === $relative ) {

src/wp-includes/script-modules.php

@@ -138,6 +138,27 @@ function wp_deregister_script_module( string $id ) {
 	wp_script_modules()->deregister( $id );
 }
 
+/**
+ * Overrides the text domain and path used to load translations for a script module.
+ *
+ * Translations for script modules are loaded automatically from the default
+ * text domain and language directory. Use this function only when a module's
+ * text domain differs from `'default'` or when translation files live outside
+ * the standard location, for example plugin modules using their own text domain.
+ *
+ * @since 7.0.0
+ *
+ * @see WP_Script_Modules::set_translations()
+ *
+ * @param string $id     The identifier of the script module.
+ * @param string $domain Optional. Text domain. Default 'default'.
+ * @param string $path   Optional. The full file path to the directory containing translation files.
+ * @return bool True if the text domain was registered, false if the module is not registered.
+ */
+function wp_set_script_module_translations( string $id, string $domain = 'default', string $path = '' ): bool {
+	return wp_script_modules()->set_translations( $id, $domain, $path );
+}
+
 /**
  * Registers all the default WordPress Script Modules.
  *