How to Internationalize and Translate WordPress Themes and Plugins

Make your WordPress themes and plugins translation-ready with internationalization (i18n). Then use PTC for AI-powered translations that understand your code, your users, and your product.

Instead of explaining the theory behind WordPress internationalization (i18n) and localization (l10n), this guide uses a demo plugin to show you:

  • How to make a WordPress plugin translation-ready
  • How to translate the text strings and integrate these translations into your plugin

Each step of this tutorial is demonstrated with code changes. Check the demo plugin’s repository to review them via Git commits.

The Goal for Our Demo Plugin: Making it Multilingual

Our demo plugin, OTGS Foo Banner, displays a banner with a customizable message on the front-end.

Message displayed by the demo plugin on the front-end

Users with access to the site’s backend also see:

An admin page to manage message status and content

A confirmation pop-up That Appears After saving changes


Our goal is to make all strings translatable and add Spanish translations. This way, users who switch WordPress to Spanish can use the plugin in their language.

Steps to WordPress Plugin Internationalization (i18n) and Localization (l10n)

1. Initialize Composer and Install WP-CLI as a Dev Dependency

If you’re not using Composer in your projects yet, initialize it by running composer init. Then, follow the command-line wizard.

Commit Reference: See commit f096381 in GitHub

To run WP-CLI commands, install WP-CLI via Composer by running:

composer require --dev wp-cli/wp-cli-bundle

Commit Reference: See commit 718606e in GitHub

2. Wrap All Texts in GetText Calls

Adding GetText Calls to PHP Code

In PHP, wrap all the hard-coded strings in gettext WordPress localization functions like __() and _e(). Specify a text domain to uniquely identify translations for your theme or plugin.

  • The __() function returns the strings
__('Hello, world!', 'your-text-domain');
  • The _e() function echoes a translatable string
_e('Hello, world!', 'your-text-domain');

These functions find the correct translation in the specified locale and domain. If no translation is available, the original string will remain unchanged.

Commit Reference: See commit 7deef5f in GitHub

Adding GetText Calls to JavaScript (JS) Code

Just like in PHP, make sure that all text in your JavaScript code can be translated into different languages.

WordPress provides the wp-i18n dependency to retrieve translations of text strings.

Specify a text domain for translations to be correctly matched and displayed based on the current language set in WordPress.

Commit Reference: See commit 7deef5f in GitHub

3. Generate the Portable Object Template (POT) File

To translate your code, you will need to generate POT files that include the original texts. You don’t need to create these files manually – below, you’ll find the WordPress commands you need to run to generate the POT files.

Here’s what the end result will look like:

An example of a POT file

Generating the POT File

You need to run a Composer script that scans all the PHP and JS files in your project, looks for GetText calls (which you previously added), and creates a .pot file that includes all the translatable strings in the project.

To do this:

  1. Add the Composer script make-pot to your project to avoid executing the full command manually each time you update the POT file.

Commit Reference: See commit faca3dd in GitHub

  1. Run the make-pot command: composer make-pot

Commit Reference: See commit 452be7f in GitHub

If your project includes bundled JavaScript scripts (for example, via Webpack), use @wordpress/babel-plugin-makepot instead. 

4. Create the Translations

PTC (Private Translation Cloud) gives you context-aware, AI-powered translations in .po, .mo, .json and l10n.php files — the exact formats WordPress needs for theme and plugin internationalization.

Create your free-trial account, which gives you full access to all PTC features for 30 days. Then, choose how to use PTC:

  • Connect your Git repository for continuous localization
  • Upload files manually to test PTC’s translations
  • Use the API to send and receive files programmatically

For this demo, we’re using the Git integration because it’s the easiest way to keep translations updated automatically as your code evolves.

Generating JED and l10n.php Files

When translating JavaScript files in WordPress, you will use JED (JSON Extended Description) files. These JSON files are generated from MO files and contain the translations needed for your JavaScript scripts. 

For optimal performance, WordPress loads JS translations only for the scripts currently in use. Each JSON translation file ends with a hash representing the relative path to the corresponding JS script, in order to accurately map the translations.

For generating the .json files, check the option “Is this a WordPress project with localizable JavaScript?” and verify the output path in the Resource Files step.

Enabling the option “Is this a WordPress project with localizable JavaScript?”
Enabling the option “Is this a WordPress project with localizable JavaScript?”

Similarly, WordPress 6.5 introduced the .l10n.php format, a new translation file type to improve the performance of loading translations.

If an .mo translation file has a corresponding .l10n.php file, the latter will be loaded instead. This is faster and uses less memory.
To generate this new format, you only need to check the Create .l10n.php files option, also available in the Resource Files section.

Selecting the Create .l10n.php files option in the Resource Files section

Merge Your Translations Files

Once you connect PTC and set your translation preferences, PTC translates your .pot file using advanced AI, and sends back .po, .mo, .json and l10n.php files via merge request.

In our demo plugin, translations are stored in the /languages/ folder.

Translation Files Commit Reference: See commit ac59f0b in GitHub

5. Configure and Load Translation Files in WordPress

Lastly, configure WordPress to recognize and load the translation files for both PHP and JavaScript components of the plugin or theme.

Load the Plugin’s Text Domain for PHP Files

Tell WordPress where it can find the translation files for your PHP code. 

Commit Reference: See commit 270424b in GitHub

Load the Script Translations for Your JavaScript Files

To load the script translations for your JavaScript files, you need to tell WordPress where to find the JSON files. In our example, we use a file named confirm.js.

Commit Reference: See commit 3a77340 in GitHub

6. Check the Translations in a Local or Sandbox Environment

Once you’ve configured WordPress to load your translation files, test your plugin in a local or sandbox environment.

Switch WordPress to your target language (in our case, Spanish) and confirm that all texts appear translated on both the front-end and admin pages.

The translated confirmation pop-up from our demo plugin

Translating the README and WordPress.org Descriptions

Your readme.txt contains important information users see, such as the plugin or theme’s description. Since this file is not a resource file like your .pot files, PTC does not detect or translate it automatically.

To translate the readme.txt with PTC:

  1. In your PTC dashboard, go to Translations → Paste to translate.
  2. Paste the parts of your readme.txt you want to translate.
  3. Choose your target languages and click Translate.
  4. Download the translated text and include it inside your theme or plugin package.

If your plugin or theme is hosted on WordPress.org, the Details tab shows the readme.txt content in the user’s language. To make these translations appear on WordPress.org:

  1. Go to your project on translate.wordpress.org.
  2. Add the translations provided by PTC.
  3. Wait for a WordPress translation editor (PTE) to review and approve them.

You can also invite trusted team members to become translation editors to help with approvals.

Seeing Untranslated Strings?

See what to check if translations don’t appear in your plugin or theme for common causes and how to fix them.

Make Your WordPress Projects Multilingual

By translating your WordPress themes and plugins, you can reach a broader, global audience. WordPress itself supports numerous languages, and your themes and plugins should too.

With PTC, you get…

Instant, Better Than Human Translations

Different setup options, including Integration with your software repository and translations sent as merge requests

Unlimited translation rounds, enhanced by AI and machine learning

Start your free 30-day trial
How to Internationalize and Translate WordPress Themes and Plugins

Start typing and press enter to search

Scroll to Top