Internationalization

目录

What is internationalization?

Internationalization is the process to provide multiple language support to software, in this case WordPress. Internationalization is often abbreviated as i18n, where 18 stands for the number of letters between the first i and the last n.

Providing i18n support to your plugin and theme allows it to reach the largest possible audience, even without requiring you to provide the additional language translations. When you upload your software to WordPress.org, all JS and PHP files will automatically be parsed. Any detected translation strings are added to translate.wordpress.org to allow the community to translate, ensuring WordPress plugins and themes are available in as many languages as possible.

For PHP, WordPress has a long established process, see How to Internationalize Your Plugin. The release of WordPress 5.0 brings a similar process for translation to JavaScript code.

How to use i18n in JavaScript

WordPress 5.0 introduced the wp-i18n JavaScript package that provides the functions needed to add translatable strings as you would in PHP.

First, add wp-i18n as a dependency when registering your script:

<?php
/**
 * Plugin Name: Myguten Plugin
 * Text Domain: myguten
 */
function myguten_block_init() {
    wp_register_script(
        'myguten-script',
        plugins_url( 'block.js', __FILE__ ),
        array( 'wp-blocks', 'react', 'wp-i18n', 'wp-block-editor' )
    );

    register_block_type( 'myguten/simple', array(
        'api_version' => 3,
        'editor_script' => 'myguten-script',
    ) );
}
add_action( 'init', 'myguten_block_init' );

In your code, you can include the i18n functions. The most common function is __ (a double underscore) which provides translation of a simple string. Here is a basic block example:

import { __ } from '@wordpress/i18n';
import { registerBlockType } from '@wordpress/blocks';
import { useBlockProps } from '@wordpress/block-editor';

registerBlockType( 'myguten/simple', {
    apiVersion: 3,
    title: __( 'Simple Block', 'myguten' ),
    category: 'widgets',

    edit: () => {
        const blockProps = useBlockProps( { style: { color: 'red' } } );

        return <p { ...blockProps }>{ __( 'Hello World', 'myguten' ) }</p>;
    },

    save: () => {
        const blockProps = useBlockProps.save( { style: { color: 'red' } } );

        return <p { ...blockProps }>{ __( 'Hello World', 'myguten' ) }</p>;
    },
} );

In the above example, the function will use the first argument for the string to be translated. The second argument is the text domain which must match the text domain slug specified by your plugin.

Common functions available, these mirror their PHP counterparts are:

Note: Every string displayed to the user should be wrapped in an i18n function.

Translating strings with HTML or embedded elements

When translating strings that contain HTML formatting elements (such as <strong>, <em>, or <a>), do not concatenate string fragments and avoid embedding raw HTML markup directly in translation strings. Concatenating fragments breaks translations because grammatical structure and word order differ across languages, while raw HTML complicates translation tools and introduces potential security issues.

Instead, use createInterpolateElement from @wordpress/element. It safely interpolates React elements and components into translated strings containing placeholder tags:

import { __ } from '@wordpress/i18n';
import { createInterpolateElement } from '@wordpress/element';

const message = createInterpolateElement(
    __( 'Please visit the <link>documentation</link> for <strong>more details</strong>.', 'my-text-domain' ),
    {
        link: <a href="https://example.com" />,
        strong: <strong />,
    }
);

When using createInterpolateElement, ensure 'wp-element' is included in your script dependencies array in wp_register_script() or wp_enqueue_script().

After all strings in your code is wrapped, the final step is to tell WordPress your JavaScript contains translations, using the wp_set_script_translations() function.

<?php
    function myguten_set_script_translations() {
        wp_set_script_translations( 'myguten-script', 'myguten' );
    }
    add_action( 'init', 'myguten_set_script_translations' );

This is all you need to make your plugin JavaScript code translatable.

When you set script translations for a handle WordPress will automatically figure out if a translations file exists on translate.wordpress.org, and if so ensure that it’s loaded into wp.i18n before your script runs. With translate.wordpress.org, plugin authors also do not need to worry about setting up their own infrastructure for translations and can rely on a global community with dozens of active locales. Read more about WordPress Translations.

Provide your own translations

You can create and ship your own translations with your plugin, if you have sufficient knowledge of the language(s) you can ensure the translations are available.

Create the translation file

The translation files must be in the JED 1.x JSON format.

To create a JED translation file, first you need to extract the strings from the text. Typically, the language files all live in a directory called languages in your plugin. Using WP-CLI, you create a .pot file using the following command from within your plugin directory:

mkdir languages
wp i18n make-pot ./ languages/myguten.pot

This will create the file myguten.pot which contains all the translatable strings from your project.

msgid ""
msgstr ""
"Project-Id-Version: Scratch Plugin\n"
"Report-Msgid-Bugs-To: https://wordpress.org/support/plugin/scratch\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"POT-Creation-Date: 2019-03-08T11:26:56-08:00\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"X-Generator: WP-CLI 2.1.0\n"
"X-Domain: myguten\n"

#. Plugin Name of the plugin
msgid "Scratch Plugin"
msgstr ""

#: block.js:6
msgid "Simple Block"
msgstr ""

#: block.js:13
#: block.js:21
msgid "Hello World"
msgstr ""

Here, msgid is the string to be translated, and msgstr is the actual translation. In the POT file, msgstr will always be empty.

This POT file can then be used as the template for new translations. You should copy the file using the language code you are going to translate, this example will use the Esperanto (eo) language:

cp myguten.pot myguten-eo.po

For this simple example, you can simply edit the .po file in your editor and add the translation to all the msgstr sets. For a larger, more complex set of translation, the GlotPress and Poedit tools exist to help.

You need also to add the Language: eo parameter. Here is full myguten-eo.po translated file

The last step to create the translation file is to convert the myguten-eo.po to the JSON format needed. For this, you can use WP-CLI’s wp i18n make-json command, which requires WP-CLI v2.2.0 and later.

wp i18n make-json myguten-eo.po --no-purge

This will generate the JSON file myguten-eo-[md5].json with the contents:

{
    "translation-revision-date": "2019-04-26T13:30:11-07:00",
    "generator": "WP-CLI/2.2.0",
    "source": "block.js",
    "domain": "messages",
    "locale_data": {
        "messages": {
            "": {
                "domain": "messages",
                "lang": "eo",
                "plural-forms": "nplurals=2; plural=(n != 1);"
            },
            "Simple Block": [ "Simpla Bloko" ],
            "Hello World": [ "Salunton mondo" ]
        }
    }
}

Load the translation file

The final part is to tell WordPress where it can look to find the translation file. The wp_set_script_translations function accepts an optional third argument that is the path it will first check for translations. For example:

<?php
    function myguten_set_script_translations() {
        wp_set_script_translations( 'myguten-script', 'myguten', plugin_dir_path( __FILE__ ) . 'languages' );
    }
    add_action( 'init', 'myguten_set_script_translations' );

WordPress will check for a file in that path with the format ${domain}-${locale}-${handle}.json as the source of translations. Alternatively, instead of the registered handle you can use the md5 hash of the relative path of the file, ${domain}-${locale} in the form of ${domain}-${locale}-${md5}.json.

Using make-json automatically names the file with the md5 hash, so it is ready as-is. You could rename the file to use the handle instead, in which case the file name would be myguten-eo-myguten-script.json.

Test translations

You will need to set your WordPress installation to Esperanto language. Go to Settings > General and change your site language to Esperanto.

With the language set, create a new post, add the block, and you will see the translations used.

Filtering translations

The outputs of the translation functions (__(), _x(), _n(), and _nx()) are filterable, see i18n Filters for full information.

版本号 #2
由 壳壳虫 创建于 2026-10-31 18:09:09 UTC
由 壳壳虫 更新于 2026-10-31 18:09:11 UTC