wp-i18n-workflow

WordPress Plugin i18n Workflow

Model note: Fully mechanical — POT generation, PO/MO compilation, and script registration are tool invocations. haiku handles all steps; no cross-file reasoning needed.

Full translation pipeline for WordPress plugins: POT generation, PO/MO compilation, JavaScript translations, translate.wordpress.org GlotPress, and language pack distribution. Covers the coding conventions and the tooling workflow.

When to use

• "Generate a POT file for my plugin", "update translation strings".
• "Set up JavaScript translations", "translate strings in React/block editor".
• "Submit to translate.wordpress.org", "set up language packs".
• "Why aren't my translations loading?", "debug missing .mo file".
• "Add translator comments", "handle plurals and context strings".

Not for: PHPCS i18n sniff violations — use wp-coding-standards. Checking i18n completeness in an audit — use wp-plugin-audit Dimension B.

Method

1. PHP i18n conventions

All translatable strings must use the plugin's text domain consistently. The text domain must match the Text Domain: header and the load_plugin_textdomain() call.

// Basic translation
__( 'Settings', 'my-plugin' )
_e( 'Save Changes', 'my-plugin' )        // echo version

// With HTML context (escape + translate combined)
esc_html__( 'Error message', 'my-plugin' )
esc_attr__( 'Tooltip text', 'my-plugin' )

// Plurals
_n( '%d item', '%d items', $count, 'my-plugin' )
sprintf( _n( '%d item', '%d items', $count, 'my-plugin' ), $count )

// Context strings (disambiguation for translators)
_x( 'Post', 'noun: a blog post', 'my-plugin' )
_ex( 'Draft', 'verb: save as draft', 'my-plugin' )

// Plural with context
_nx( '%d reply', '%d replies', $count, 'comment count', 'my-plugin' )

Translator comments — required for strings with placeholders:

/* translators: %s: plugin version number */
sprintf( __( 'Version %s', 'my-plugin' ), MY_PLUGIN_VERSION )

/* translators: 1: post title, 2: author name */
sprintf( __( '"%1$s" by %2$s', 'my-plugin' ), $title, $author )

Comment must be on the line immediately before the function call and start with translators:.