wp_localize_script( string $handle, string $object_name, array $l10n )

Localize a script.

Contents

Description 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 See also

Top ↑

Parameters 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.

Top ↑

Return Return

(bool) True if the script was successfully localized, false otherwise.

Top ↑

Source 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__ );
		return false;
	}

	return $wp_scripts->localize( $handle, $object_name, $l10n );
}

Expand full source code Collapse full source code View on Trac

Top ↑

Changelog Changelog

Changelog
Version Description
2.2.0 Introduced.

Top ↑

Top ↑

Used By Used By

Used By
Used By Description
wp-admin/includes/class-wp-site-health.php: WP_Site_Health::enqueue_scripts()

Enqueues the site health scripts.
wp-includes/script-loader.php: wp_localize_community_events()

Localizes community events data that needs to be passed to dashboard.js.
wp-includes/theme.php: the_custom_header_markup()

Print the markup for a custom header.
wp-includes/class-wp-customize-nav-menus.php: WP_Customize_Nav_Menus::enqueue_scripts()

Enqueue scripts and styles for Customizer pane.
wp-includes/customize/class-wp-customize-background-image-control.php: WP_Customize_Background_Image_Control::enqueue()

Enqueue control related scripts/styles.
wp-admin/includes/class-wp-plugins-list-table.php: WP_Plugins_List_Table::prepare_items()
wp-admin/includes/class-wp-ms-themes-list-table.php: WP_MS_Themes_List_Table::prepare_items()
wp-admin/includes/class-wp-plugin-install-list-table.php: WP_Plugin_Install_List_Table::prepare_items()
wp-includes/class-wp-customize-manager.php: WP_Customize_Manager::enqueue_control_scripts()

Enqueue scripts for customize controls.
wp-includes/media.php: wp_enqueue_media()

Enqueues all scripts, styles, settings, and templates necessary to use all media JS APIs.
wp-includes/customize/class-wp-customize-header-image-control.php: WP_Customize_Header_Image_Control::enqueue()
wp-includes/script-loader.php: wp_just_in_time_script_localization()

Load localized data on print rather than initialization.
Show 7 more used by Hide more used by

Top ↑

User Contributed Notes User Contributed Notes

  1. Skip to note 1 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 8You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    Example

    // Register the script
wp_register_script( 'some_handle', 'path/to/myscript.js' );

// Localize the script with new data
$translation_array = array(
	'some_string' => __( 'Some string to translate', 'plugin-domain' ),
	'a_value' => '10'
);
wp_localize_script( 'some_handle', 'object_name', $translation_array );

// Enqueued script with localized data.
wp_enqueue_script( 'some_handle' );

    You can access the variables in JavaScript as follows:

    // alerts 'Some string to translate'
alert( object_name.some_string );

    Note: The data in the resulting JavaScript call will be passed as text (see ticket #25280). If you are trying to pass integers you will need to call the JavaScript parseInt() function.

    // Call a function that needs an int.
FinalZoom = map.getBoundsZoomLevel( bounds ) - parseInt( object_name.a_value, 10 );
  2. Skip to note 2 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 8You must log in to vote on the helpfulness of this note
    Contributed by Aamer Shahzad —

    to send ajax request from theme files we can use wp_localize_script to globally declare our javascript variables.

    function theme_enqueue_scripts() {
	/**
	 * frontend ajax requests.
	 */
	wp_enqueue_script( 'frontend-ajax', JS_DIR_URI . 'frontend-ajax.js', array('jquery'), null, true );
	wp_localize_script( 'frontend-ajax', 'frontend_ajax_object',
		array( 
			'ajaxurl' => admin_url( 'admin-ajax.php' ),
			'data_var_1' => 'value 1',
			'data_var_2' => 'value 2',
		)
	);
}
add_action( 'wp_enqueue_scripts', 'theme_enqueue_scripts' );

    in our js file we can use any of the globally declared variable frontend_ajax_object.ajaxurl, frontend_ajax_object.data_var_1, frontend_ajax_object.data_var_1.

    jQuery(document).ready(function($) {
	$.ajax({
        url: frontend_ajax_object.ajaxurl,
        type: 'get',
        data: {
            'action':'states_city_filter'
        },
        success: function( response ) {
        	console.log(response);
        },
    });
});
  3. Skip to note 3 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    Example

    // Register the script
wp_register_script( 'some_handle', 'path/to/myscript.js' );

// Localize the script with new data
$translation_array = array(
	'some_string' => __( 'Some string to translate', 'textdomain' ),
	'a_value' => '10'
);
wp_localize_script( 'some_handle', 'object_name', $translation_array );

// Enqueued script with localized data.
wp_enqueue_script( 'some_handle' );

    You can access the variables in JavaScript as follows:

    <script>
	// alerts 'Some string to translate'
	alert( object_name.some_string);
</script>
  4. Skip to note 4 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note
    Contributed by Aurovrata Venet —

    Note, calling this function multiple times in the a single session with the same object name will overwrite previous values,

    wp_localize_script( 'some_handle', 'object_name', $value1 );
... code executed again...
wp_localize_script( 'some_handle', 'object_name', $value2 ); // object_name is now set to $value2.

    If you need to have multiple data sets associated with the same script (handle), then you need to rename your object,

    wp_localize_script( 'some_handle', 'object_name1', $value1 );
... code executed again...
wp_localize_script( 'some_handle', 'object_name2', $value2 );
  5. Skip to note 5 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note
    Contributed by Ian Dunn —

    `wp_localize_script()` is 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 WP v4.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.

You must log in before being able to contribute a note or feedback.