The Definitive 4-Step Short Guide to Implementing WordPress Language Files

WordPress: 5.5.1

The reason to call this post “definitive” is because it contains the exact information (without adding anything extra) for implementing WordPress language files (aka internationalization).

The 4-Steps

1. The plugin entry point “.php” file needs the following Text Domain WordPress directive, considering foo-bar as the plugin name:

* Text Domain: foo-bar

Where is the The Text Domain used? For example, in the 2nd argument of _e() and __() functions.

The Domain Path directive didn’t need to be specified even though the plugin wasn’t part of the official WordPress plugin directory as specified here: https://developer.wordpress.org/plugins/internationalization/how-to-internationalize-your-plugin/

2. Create a “lang” folder (to put all your .mo and .po translation files) under your plugin folder:

~/wp-content/plugins/foo-bar/lang 

Folder name “lang” is preferred to “languages” because it’s shorter.

3. Create the .mo and .po language translation files via PoeEdit and make sure to prefix them with the plugin name:

  • foo-bar-en_US.mo
  • foo-bar-en_US.po
  • foo-bar-fr_FR.mo
  • foo-bar-fr_FR.po

PoeEdit is a bit awkward to use at first, but it gets the job done. Beginners need to refer to a quick-guide on how to generate the .mo and .po files.

4. Load the language translation files from the plugin entry point “.php” file like this (the folder pointing to the language files is a relative path):

add_action('plugin_loaded', function () { 
    load_plugin_textdomain('foo-bar', false, 'foo-bar/lang'); 
}); 

For better code organization a static function under a class is highly recommended, instead of the anonymous function above (the 2nd argument to add_action).

2 Common Mistakes to Avoid

  • Don’t forget to prefix the language files with the plugin name (see step 1 above).
  • Don’t forget to specify relative folder and not absolute folder (see step 4 above).