wp_localize_script( string $handle, string $object_name, array $l10n )
Localize a script.
Description
Works only if the script has already been added.
Accepts an associative array $l10n and creates a JavaScript object:
"$object_name" = {
key: value,
key: value,
...
}See also
Parameters
- $handle
-
(string) (Required) Script handle the data will be attached to.
- $object_name
-
(string) (Required) Name for the JavaScript object. Passed directly, so it should be qualified JS variable. Example: '/[a-zA-Z0-9_]+/'.
- $l10n
-
(array) (Required) The data itself. The data can be either a single or multi-dimensional array.
Return
(bool) True if the script was successfully localized, false otherwise.
More Information
This function localizes a registered script with data for a JavaScript variable.
This lets you offer properly localized translations of any strings used in your script. This is necessary because WordPress currently only offers a localization API in PHP, not directly in JavaScript (but see ticket #20491).
Though localization is the primary use, it was often used to pass generic data from PHP to JavaScript, because it was originally the only official way to do that. wp_add_inline_script() was introduced in WordPress Version 4.5, and is now the best practice for that use case. `wp_localize_script()` should only be used when you actually want to localize strings.
$object_name is the name of the variable which will contain the data. Note that this should be unique to both the script and to the plugin or theme. Thus, the value here should be properly prefixed with the slug or another unique value, to prevent conflicts. However, as this is a JavaScript object name, it cannot contain dashes. Use underscores or camelCasing.
$l10n is the data itself. The data can be either a single- or multi- (as of 3.3) dimensional array. Like json_encode(), the data will be a JavaScript object if the array is an associate array (a map), otherwise the array will be a JavaScript array.
IMPORTANT! wp_localize_script() MUST be called after the script has been registered using wp_register_script() or wp_enqueue_script().
Furthermore, the actual output of the JavaScript <script> a tag containing your localization variable occurs at the time that the enqueued script is printed (output/included on the page). This has some significant repercussions if you enqueue your script as you should using the appropriate actions (wp_enqueue_scripts and admin_enqueue_scripts), but wish to localize later using data that is not available at enqueue time.
In this case, consider enqueueing your script with the in_footer argument set to true, to delay the printing of your script include until much later in the page build (ie: wp_enqueue_script( $slug, $URL, $deps, $ver, true ); ).
The last chance to localize your script would then be on the 'wp_print_footer_scripts' hook.
Source
File: wp-includes/functions.wp-scripts.php
function wp_localize_script( $handle, $object_name, $l10n ) {
global $wp_scripts;
if ( ! ( $wp_scripts instanceof WP_Scripts ) ) {
_wp_scripts_maybe_doing_it_wrong( __FUNCTION__, $handle );
return false;
}
return $wp_scripts->localize( $handle, $object_name, $l10n );
} Changelog
| Version | Description |
|---|---|
| 2.2.0 | Introduced. |
© 2003–2021 WordPress Foundation
Licensed under the GNU GPLv2+ License.
https://developer.wordpress.org/reference/functions/wp_localize_script