Function Reference/wp localize script

1 Description
2 Usage
3 Parameters
4 Example
5 Notes
6 Source File
7 Resources
8 Related

Description

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 can be used to make any data available to your script that you can normally only get from the server side of WordPress.

Usage

<?php wp_localize_script( $handle, $name, $data ); ?>

Parameters

$handle

(string) (required) The registered script handle you are attaching the data for.

Default: None

$name

(string) (required) 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.

Default: None

$data

(array) (required) 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.

Default: None

Example

<?php

// 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:

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

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.

<script>
// Call a function that needs an int.
FinalZoom = map.getBoundsZoomLevel( bounds ) - parseInt( object_name.a_value, 10 ); 
</script>

Another example in case you need the plugins URL, which might be handy:

PHP:

wp_enqueue_script('my-script', get_stylesheet_directory_uri() . '/js/my-script.js');
wp_localize_script('my-script', 'myScript', array(
    'pluginsUrl' => plugins_url(),
));

Now you will have access to myScript.pluginsUrl in your script file:

Javascript:

var href = myScript.pluginsUrl + '/path/to/resource';

Notes

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> 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_localize_script() is located in wp-includes/functions.wp-scripts.php.

Resources

Use wp_localize_script, It Is Awesome

Enqueue Styles

Enqueue Scripts

Front-End Hooks

Admin Hooks

Login Hooks

login_enqueue_scripts

See also index of Function Reference and index of Template Tags.

This article is marked as in need of editing. You can help Codex by editing it.

WordPress.org

Codex