Title: The commonly used Internationalization functions
Published: 11 May 2024
Last modified: 31 July 2024

---

[Home](https://learn.wordpress.org)[Courses](https://learn.wordpress.org/courses/)
[Beginner WordPress Developer](https://learn.wordpress.org/course/beginner-wordpress-developer/)
The commonly used Internationalization functions

 [ Exit Course ](https://learn.wordpress.org/course/beginner-wordpress-developer/)

 1.   a.  [   WordPress and web servers  ](https://learn.wordpress.org/lesson/wordpress-and-web-servers/)
         [Preview](https://learn.wordpress.org/lesson/wordpress-and-web-servers/)
      b.  [   The WordPress file structure  ](https://learn.wordpress.org/lesson/the-wordpress-file-structure/)
         [Preview](https://learn.wordpress.org/lesson/the-wordpress-file-structure/)
      c.  [   The WordPress database  ](https://learn.wordpress.org/lesson/the-wordpress-database/)
         [Preview](https://learn.wordpress.org/lesson/the-wordpress-database/)
      d.  [   Permalinks, rewriting urls on Apache and Nginx  ](https://learn.wordpress.org/lesson/permalinks-rewriting-urls-on-apache-and-nginx/)
         [Preview](https://learn.wordpress.org/lesson/permalinks-rewriting-urls-on-apache-and-nginx/)
      e.  [   Front-end page request  ](https://learn.wordpress.org/lesson/front-end-page-request/)
         [Preview](https://learn.wordpress.org/lesson/front-end-page-request/)
      f.  [   Admin page request  ](https://learn.wordpress.org/lesson/admin-page-request/)
         [Preview](https://learn.wordpress.org/lesson/admin-page-request/)
 2.   6 lessons
 3.   a.  [   Local development environment  ](https://learn.wordpress.org/lesson/local-development-environment/)
         [Preview](https://learn.wordpress.org/lesson/local-development-environment/)
      b.  [   WordPress Installation  ](https://learn.wordpress.org/lesson/wordpress-installation/)
         [Preview](https://learn.wordpress.org/lesson/wordpress-installation/)
      c.  [   Code editor  ](https://learn.wordpress.org/lesson/code-editor/) [Preview](https://learn.wordpress.org/lesson/code-editor/)
      d.  [   Other useful development tools  ](https://learn.wordpress.org/lesson/other-useful-development-tools/)
         [Preview](https://learn.wordpress.org/lesson/other-useful-development-tools/)
 4.   4 lessons
 5.   a.  [   HTML  ](https://learn.wordpress.org/lesson/html/) [Preview](https://learn.wordpress.org/lesson/html/)
      b.  [   CSS  ](https://learn.wordpress.org/lesson/css/) [Preview](https://learn.wordpress.org/lesson/css/)
      c.  [   JavaScript  ](https://learn.wordpress.org/lesson/javascript/) [Preview](https://learn.wordpress.org/lesson/javascript/)
      d.  [   PHP  ](https://learn.wordpress.org/lesson/php/) [Preview](https://learn.wordpress.org/lesson/php/)
      e.  [   MySQL  ](https://learn.wordpress.org/lesson/mysql/) [Preview](https://learn.wordpress.org/lesson/mysql/)
 6.   5 lessons
 7.   a.  [   WordPress Hooks  ](https://learn.wordpress.org/lesson/wordpress-hooks/) 
         [Preview](https://learn.wordpress.org/lesson/wordpress-hooks/)
      b.  [   Action Hooks  ](https://learn.wordpress.org/lesson/action-hooks/) [Preview](https://learn.wordpress.org/lesson/action-hooks/)
      c.  [   Filter Hooks  ](https://learn.wordpress.org/lesson/filter-hooks/) [Preview](https://learn.wordpress.org/lesson/filter-hooks/)
      d.  [   Working with hooks  ](https://learn.wordpress.org/lesson/working-with-hooks/)
         [Preview](https://learn.wordpress.org/lesson/working-with-hooks/)
 8.   4 lessons
 9.   a.  [   Introduction to themes for developers  ](https://learn.wordpress.org/lesson/what-is-a-theme/)
         [Preview](https://learn.wordpress.org/lesson/what-is-a-theme/)
      b.  [   Theme structure  ](https://learn.wordpress.org/lesson/theme-structure/) 
         [Preview](https://learn.wordpress.org/lesson/theme-structure/)
      c.  [   Main stylesheet  ](https://learn.wordpress.org/lesson/main-stylesheet/) 
         [Preview](https://learn.wordpress.org/lesson/main-stylesheet/)
      d.  [   Templates  ](https://learn.wordpress.org/lesson/templates-3/) [Preview](https://learn.wordpress.org/lesson/templates-3/)
      e.  [   Global settings and styles  ](https://learn.wordpress.org/lesson/global-settings-and-styles/)
         [Preview](https://learn.wordpress.org/lesson/global-settings-and-styles/)
      f.  [   Create Block Theme plugin  ](https://learn.wordpress.org/lesson/create-block-theme-plugin/)
         [Preview](https://learn.wordpress.org/lesson/create-block-theme-plugin/)
 10.  6 lessons
 11.  a.  [   What is a plugin?  ](https://learn.wordpress.org/lesson/what-is-a-plugin/)
         [Preview](https://learn.wordpress.org/lesson/what-is-a-plugin/)
      b.  [   Plugin requirements  ](https://learn.wordpress.org/lesson/plugin-requirements/)
         [Preview](https://learn.wordpress.org/lesson/plugin-requirements/)
      c.  [   Custom post types  ](https://learn.wordpress.org/lesson/custom-post-types/)
         [Preview](https://learn.wordpress.org/lesson/custom-post-types/)
      d.  [   Custom taxonomies  ](https://learn.wordpress.org/lesson/custom-taxonomies/)
         [Preview](https://learn.wordpress.org/lesson/custom-taxonomies/)
      e.  [   Custom post type data  ](https://learn.wordpress.org/lesson/custom-post-type-data/)
         [Preview](https://learn.wordpress.org/lesson/custom-post-type-data/)
      f.  [   Enqueuing CSS or JavaScript  ](https://learn.wordpress.org/lesson/enqueuing-css-or-javascript/)
         [Preview](https://learn.wordpress.org/lesson/enqueuing-css-or-javascript/)
 12.  6 lessons
 13.  a.  [   Setting up your block development environment  ](https://learn.wordpress.org/lesson/setting-up-your-block-development-environment/)
         [Preview](https://learn.wordpress.org/lesson/setting-up-your-block-development-environment/)
      b.  [   Scaffolding a new block  ](https://learn.wordpress.org/lesson/scaffolding-a-new-block/)
         [Preview](https://learn.wordpress.org/lesson/scaffolding-a-new-block/)
      c.  [   Building your first block  ](https://learn.wordpress.org/lesson/building-your-first-block/)
         [Preview](https://learn.wordpress.org/lesson/building-your-first-block/)
      d.  [   Block functionality  ](https://learn.wordpress.org/lesson/block-functionality/)
         [Preview](https://learn.wordpress.org/lesson/block-functionality/)
      e.  [   Block attributes  ](https://learn.wordpress.org/lesson/block-attributes-2/)
         [Preview](https://learn.wordpress.org/lesson/block-attributes-2/)
      f.  [   Block supports and styles  ](https://learn.wordpress.org/lesson/block-supports-and-styles/)
         [Preview](https://learn.wordpress.org/lesson/block-supports-and-styles/)
      g.  [   Static vs dynamic blocks  ](https://learn.wordpress.org/lesson/static-vs-dynamic-blocks/)
         [Preview](https://learn.wordpress.org/lesson/static-vs-dynamic-blocks/)
 14.  7 lessons
 15.  a.  [   The WordPress REST API  ](https://learn.wordpress.org/lesson/the-wordpress-rest-api/)
         [Preview](https://learn.wordpress.org/lesson/the-wordpress-rest-api/)
      b.  [   Using the WordPress REST API  ](https://learn.wordpress.org/lesson/using-the-wordpress-rest-api/)
         [Preview](https://learn.wordpress.org/lesson/using-the-wordpress-rest-api/)
      c.  [   Interacting with the WordPress REST API  ](https://learn.wordpress.org/lesson/interacting-with-the-wordpress-rest-api/)
         [Preview](https://learn.wordpress.org/lesson/interacting-with-the-wordpress-rest-api/)
      d.  [   Extending the WordPress REST API  ](https://learn.wordpress.org/lesson/extending-the-wordpress-rest-api/)
         [Preview](https://learn.wordpress.org/lesson/extending-the-wordpress-rest-api/)
 16.  4 lessons
 17.  a.  [   Securely developing plugins and themes  ](https://learn.wordpress.org/lesson/securely-developing-plugins-and-themes/)
         [Preview](https://learn.wordpress.org/lesson/securely-developing-plugins-and-themes/)
      b.  [   Fixing common security vulnerabilities  ](https://learn.wordpress.org/lesson/fixing-common-security-vulnerabilities/)
         [Preview](https://learn.wordpress.org/lesson/fixing-common-security-vulnerabilities/)
      c.  [   Tools to detect security vulnerabilities  ](https://learn.wordpress.org/lesson/tools-to-detect-security-vulnerabilities/)
         [Preview](https://learn.wordpress.org/lesson/tools-to-detect-security-vulnerabilities/)
 18.  3 lessons
 19.  a.  [   What is Internationalization?  ](https://learn.wordpress.org/lesson/what-is-internationalization/)
         [Preview](https://learn.wordpress.org/lesson/what-is-internationalization/)
      b.  [   The commonly used Internationalization functions  ](https://learn.wordpress.org/lesson/the-commonly-used-internationalization-functions/)
         [Preview](https://learn.wordpress.org/lesson/the-commonly-used-internationalization-functions/)
 20.  2 lessons
 21.  a.  [   Setting up a WordPress multisite network  ](https://learn.wordpress.org/lesson/setting-up-a-wordpress-multisite-network/)
         [Preview](https://learn.wordpress.org/lesson/setting-up-a-wordpress-multisite-network/)
      b.  [   Managing a WordPress multisite network  ](https://learn.wordpress.org/lesson/managing-a-wordpress-multisite-network/)
         [Preview](https://learn.wordpress.org/lesson/managing-a-wordpress-multisite-network/)
      c.  [   Advanced multisite management  ](https://learn.wordpress.org/lesson/advanced-multisite-management/)
         [Preview](https://learn.wordpress.org/lesson/advanced-multisite-management/)
      d.  [   Developing for a multisite network  ](https://learn.wordpress.org/lesson/developing-for-a-multisite-network/)
         [Preview](https://learn.wordpress.org/lesson/developing-for-a-multisite-network/)
      e.  [   Building plugins and themes that support multisite  ](https://learn.wordpress.org/lesson/building-plugins-and-themes-that-support-multisite/)
         [Preview](https://learn.wordpress.org/lesson/building-plugins-and-themes-that-support-multisite/)
 22.  5 lessons
 23.  a.  [   The built-in WordPress debugging options  ](https://learn.wordpress.org/lesson/the-built-in-wordpress-debugging-options/)
         [Preview](https://learn.wordpress.org/lesson/the-built-in-wordpress-debugging-options/)
      b.  [   Examining the state of your PHP code  ](https://learn.wordpress.org/lesson/examining-the-state-of-your-php-code/)
         [Preview](https://learn.wordpress.org/lesson/examining-the-state-of-your-php-code/)
      c.  [   Examining the state of your JavaScript code  ](https://learn.wordpress.org/lesson/examining-the-state-of-your-javascript-code/)
         [Preview](https://learn.wordpress.org/lesson/examining-the-state-of-your-javascript-code/)
      d.  [   Useful debugging plugins  ](https://learn.wordpress.org/lesson/useful-debugging-plugins/)
         [Preview](https://learn.wordpress.org/lesson/useful-debugging-plugins/)
 24.  4 lessons
 25.  a.  [   Quiz time  ](https://learn.wordpress.org/lesson/quiz-time/)
 26.  1 lesson, 1 quiz
 27.  a.  [   Time to test your skills  ](https://learn.wordpress.org/lesson/time-to-test-your-skills/)
 28.  1 lesson, 1 quiz
 29.  a.  [   Test your knowledge  ](https://learn.wordpress.org/lesson/test-your-knowledge/)
 30.  1 lesson, 1 quiz

### An introduction to Internationalization

# The commonly used Internationalization functions

In order to get started on internationalizing your code, you need to understand 
the functions that WordPress provides to help you with this process.

In this lesson, you will learn about the most commonly used internationalization
functions in WordPress, and how to use them in your code.

## How to internationalize your code (0:18)

Whenever you find yourself writing a string of text that will be displayed to the
user, you should use the [WordPress i18n functions](https://developer.wordpress.org/apis/internationalization/internationalization-functions/)
to make sure it can be translated.

There are a number of i18n functions available, with each performing a different
task related to internationalization.

The most commonly used i18n function is the `__()` function. This function takes
a string of text and returns the translated version of that string. If no translation
is available, it returns the original string.

You will also notice that this function, and most other i18n functions, takes a 
second parameter. This parameter is used to specify the text domain.

A text domain is a unique identifier for your plugin or theme. It is used to make
sure that the correct translations are used.

Both themes and plugins have a Text Domain field in their header. This is used to
specify the text domain for the theme or plugin.

Whenever you use a translation function, you should always include the text domain
as the second parameter.

    ```php
    __( 'Some Text', 'my-textdomain' );
    ```

To see how this works, let’s take a look at an example:

Start by browsing to the [Beginner Developer Learning Pathway repository](https://github.com/wptrainingteam/beginner-developer/)
on GitHub and download the [Internationalization Theme](https://github.com/wptrainingteam/beginner-developer/raw/main/internationalization.zip)
zip file.

Then install the theme on your WordPress site, and browse to it in your code editor.

In the `functions.php` file a JavaScript file is enqueued in the context of the 
WordPress dashboard, It also registers a submenu item in the Appearance menu, which
renders a theme settings page.

    ```php
    <?php
    /**
     * Enqueue theme.js file in the dashboard.
     */
    add_action( 'admin_enqueue_scripts', 'internationalization_enqueue_scripts' );
    function internationalization_enqueue_scripts() {
        wp_enqueue_script(
            'internationalization-theme-js',
            get_stylesheet_directory_uri() . '/assets/theme.js',
            array(),
            '1.0.0',
            true
        );
    }

    /**
     * Create a submenu item under the "Appearance" menu.
     */
    add_action( 'admin_menu', 'internationalization_add_submenu_page' );
    function internationalization_add_submenu_page() {
        add_submenu_page(
            'themes.php',
            'Internationalization',
            'Internationalization',
            'manage_options',
            'internationalization',
            'internationalization_display_page'
        );
    }

    /**
     * Render the page for the submenu item.
     */
    function internationalization_display_page() {
        ?>
        <div class="wrap">
            <h1>Internationalization Settings</h1>
            <p>This is a settings page for the Internationalization theme</p>
            <button id="internationalization-settings-button" class="button button-primary">Alert</button>
        </div>
        <?php
    }
    ```

If you browse to the settings page, it contains a button, which when clicked shows
an alert.

This alert is handled in the JavaScript file for the theme.

    ```javascript
    /**
     * Add event listener to the button
     */
    document.querySelector( '#internationalization-settings-button' ).addEventListener( 'click', function(){
        alert( 'Settings button clicked' );
    } );
    ```

In this code, you have a number of English text strings that need to be internationalized.

The first step is to internationalize the text strings in the PHP code. To do this,
you can wrap text strings in the `__()` function and specify the text domain.

Start by checking the Text Domain for the theme. For themes this is in the style.
css file, and for plugins, it is in the main plugin file.

In this case, the text domain is `internationalization`. If this theme didn’t have
a text domain, you would need to specify one.

Then, update the text strings in the `internationalization_add_submenu_page()` function.

    ```php
    /**
     * Create an admin submenu item under the "Appearance" menu.
     */
    add_action( 'admin_menu', 'internationalization_add_submenu_page' );
    function internationalization_add_submenu_page() {
        add_submenu_page(
            'themes.php',
            __( 'Internationalization', 'internationalization' ),
            __( 'Internationalization', 'internationalization' ),
            'manage_options',
            'internationalization',
            'internationalization_display_page'
        );
    }
    ```

You can do the same for the text strings in the `internationalization_display_page()`
function.

    ```php
    /**
     * Render the page for the submenu item.
     */
    function internationalization_display_page() {
        ?>
        <div class="wrap">
            <h1><?php echo __( 'Internationalization Settings', 'internationalization' ); ?></h1>
            <p><?php echo __( 'This is a settings page for the Internationalization theme', 'internationalization' ); ?></p>
            <button id="internationalization-settings-button" class="button button-primary"><?php echo __( 'Alert', 'internationalization' ); ?></button>
        </div>
        <?php
    }
    ```

WordPress also contains a shorthand function to echo a translatable string. This
function is the `_e()` [function](https://developer.wordpress.org/reference/functions/_e/).
It both internationalizes and then echoes the string. You can use this function 
to simplify your code.

    ```php
    /**
     * Render the page for the submenu item.
     */
    function internationalization_display_page() {
        ?>
        <div class="wrap">
            <h1><?php _e( 'Internationalization Settings', 'internationalization' ); ?></h1>
            <p><?php _e( 'This is a settings page for the Internationalization theme', 'internationalization' ); ?></p>
            <button id="internationalization-settings-button" class="button button-primary"><?php echo __( 'Alert', 'internationalization' ); ?></button>
        </div>
        <?php
    }
    ```

Next, you need to internationalize the text strings in the JavaScript file.

To do this, there is a JavaScript equivalent to the PHP `__()` function, which is
available in the `wp.i18n` object on the WordPress front end.

To ensure that you can use this function, you need to update your `internationalization_enqueue_scripts()`
function to require the `wp-i18n` package as a dependency. This will ensure that
your JavaScript code is only loaded when the `wp-i18n` package loaded and the `wp.
i18n` object is available.

    ```php
    /**
     * Enqueue theme.js file in the dashboard.
     */
    add_action( 'admin_enqueue_scripts', 'internationalization_enqueue_scripts' );
    function internationalization_enqueue_scripts() {
        wp_enqueue_script(
            'internationalization-theme-js',
            get_stylesheet_directory_uri() . '/assets/theme.js',
            array( 'wp-i18n' ),
            '1.0.0',
            true
        );
    }
    ```

Then, you need to call the wp_set_script_translations function for the script you
want to translate. This function takes the handle of the script and the text domain
as parameters. This will load the translations for the script.

    ```php
    wp_set_script_translations( 'internationalization-theme-js', 'internationalization' );
    ```

With this done, you can then set up and use the `__()` function from the `wp.i18n`
object to translate the text string in your JavaScript file.

    ```javascript
    const __ = wp.i18n.__;
    /**
     * Add event listener to the button
     */
    document.querySelector( '#internationalization-settings-button' ).addEventListener( 'click', function(){
        alert( wp.i18n.__( 'Settings button clicked', 'internationalization' ) );
    } );
    ```

If you refresh the page, you won’t immediately see any changes, and all functionality
will still work as expected.

However, if someone wanted to, they could generate the English language file for
the theme, based on all the internationalized text strings, to allow for translation.

## Internationalization functions in block development

If you are developing a block for the block editor, you can also use the JavaScript
translation functions in your block’s JavaScript to internationalize the text strings
in your block.

All you need to do to use it is to import the relevant functions from the `@wordpress/
i18n` [package](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/).

    ```php
    /**
     * Retrieves the translation of text.
     *
     * @see https://developer.wordpress.org/block-editor/reference-guides/packages/packages-i18n/
     */
    import { __ } from '@wordpress/i18n';
    ```

## Further reading

This lesson only covers a handful of the available internationalization functions.
For more information on all the available functions, check out the [Internationalization](https://developer.wordpress.org/apis/internationalization/)
section in the Common APIs handbook of the WordPress developer resources.

 This is a preview lesson

Register or sign in to take this lesson.

 [ Take course ](https://learn.wordpress.org/course/beginner-wordpress-developer/)

 [ Sign in ](https://login.wordpress.org/?redirect_to=https%3A%2F%2Flearn.wordpress.org%2Flesson%2Fthe-commonly-used-internationalization-functions%2F&locale=en_US)

##  Suggestions

 Found a typo, grammar error or outdated screenshot? [Contact us](https://learn.wordpress.org/report-content-feedback/).