DEV Community

Cover image for Integrating i18n into a Modern WordPress & React Plugin
Forhad Khan
Forhad Khan

Posted on

Integrating i18n into a Modern WordPress & React Plugin

#wordpress #react #i18n

This guide outlines the step-by-step approach to implementing internationalization (i18n) using a modern stack (Bun/npm/yarn/pnpm), Composer, React (via @wordpress/scripts), and a local WP-CLI bundle.

1. Tooling & Dependencies

PHP (Local WP-CLI)

Instead of requiring a global system installation, bundle WP-CLI's translation tools directly in your project:

composer require --dev wp-cli/i18n-command
Enter fullscreen mode Exit fullscreen mode

JavaScript

Install the WordPress i18n utility using your preferred package manager:

# Bun
bun add @wordpress/i18n

# npm
npm install @wordpress/i18n --save

# pnpm
pnpm add @wordpress/i18n

# yarn
yarn add @wordpress/i18n
Enter fullscreen mode Exit fullscreen mode

2. String Wrapping

In React (TSX/JS)

Import the __ function and use your plugin's text domain.

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

export const MyComponent = () => (
    <h1>{__('Hello from React', 'my-plugin-domain')}</h1>
);
Enter fullscreen mode Exit fullscreen mode

In PHP

Use standard WordPress functions.

echo __('Settings', 'my-plugin-domain');
Enter fullscreen mode Exit fullscreen mode

3. Automation Scripts

Add these to your package.json. We use the PHP bootstrapper to ensure the local WP-CLI bundle runs on any environment (Windows, Mac, Linux) without assuming a global binary.

{
  "scripts": {
    "i18n:make-pot": "php vendor/wp-cli/wp-cli/php/boot-fs.php i18n make-pot . languages/plugin-domain.pot --domain=plugin-domain --exclude=node_modules,vendor,dist",
    "i18n:make-json": "php vendor/wp-cli/wp-cli/php/boot-fs.php i18n make-json languages --no-purge"
  }
}
Enter fullscreen mode Exit fullscreen mode

4. Runtime Integration

Tell WordPress where to find the JSON translation files for your React application. This is typically done in your Admin or Main plugin class:

add_action('admin_enqueue_scripts', function() {
    // ... your script registration ...

    wp_set_script_translations(
        'my-script-handle', // The handle used in wp_enqueue_script
        'my-plugin-domain',
        plugin_dir_path( __FILE__ ) . 'languages'
    );
});
Enter fullscreen mode Exit fullscreen mode

5. The Production Workflow

Follow these steps whenever strings change:

Build:

  • bun run build (or npm/yarn/pnpm)
  • Why? WP-CLI extracts React strings from the compiled JavaScript in assets/, not the raw .tsx source.

Extract:

  • bun run i18n:make-pot (or npm run ...)
  • Scan PHP and compiled JS to update the template.

Translate:

  • Open languages/plugin-domain.pot in Poedit and save as plugin-domain-{locale}.po (e.g., productbay-es_ES.po).

Convert:

  • bun run i18n:make-json (or npm run ...)
  • Generate the .json files that WordPress loads for the React frontend.

Summary of the Approach

  • Source of Truth: The built assets (for React) and PHP source.
  • Portability: Uses vendor/bin (boot-fs.php) to avoid "it works on my machine" issues.
  • Efficiency: One command for extraction, one for deployment.

Top comments (0)