How Plugin Translations Are Handled

I’ve been trying to decipher how the new system works to include language packs when your plugin is installed from rather than experimenting on my own published plugins.

At a high level, only languages that are translated 100% and approved are included as language packs.

I’ve included some frequently asked questions and responses I can glean from posts and comments on those posts on, along with comments from other plugin developers.  They’ll be updated as I get more information, and if you see any questions that are missing or something that’s wrong, let me know!

How do I use translations from in my plugins?

If you have existing translations, make sure they are in the languages folder of your plugin.

Include a call to load_plugin_textdomain in your main plugin file.  As an example for Event Calendar Newsletter:

 * Load in any language files that we have setup
function ecn_load_textdomain() {
    load_plugin_textdomain( 'event-calendar-newsletter', false, plugin_basename( dirname( __FILE__ ) ) . '/languages' );
add_action( 'plugins_loaded', 'ecn_load_textdomain' );

You also need to make sure the text domain matches your plugins slug.  This is a requirement for using translations.

Why use translation rather than including translation files inside your plugin?

The main reasons are:

1) Ease of translating without using a 3rd party program like Poedit
2) Smaller download sizes for your plugins since you don’t need to include the translation files
3) Ability to translate your plugin’s readme.txt

What if version 1.5 of your plugin is 100% but 1.6 is 99%, what language packs are used?

As far as I can see, sites installing 1.6 of your plugin for the first time will get the 1.5 translations.  If a site has 1.5 installed and upgrades to 1.6, then they will still keep the 1.5 translations and the rest will be in the language you wrote them in.

You can push updates to your plugins SVN /trunk before pushing a new tagged version to make the strings available for translation ahead of time.  But if you push a version to /trunk and some strings get translated before you release a new tagged version, those strings might need to be re-translated again.  Otto discusses this in a comment on

What if I already have translations included in my plugin, will they be imported to

They will only be imported once if they are correctly included and your text domain matches your plugin slug.  If not, you’ll need to make a request on Slack’s #meta-i18n for your plugin translations to be re-imported.

Can I opt out of using

Yes, you can just include your own translations within your plugin.  These will override any translation packs from

Can I debug any issues with importing my translation strings into

Yes, you can join the #meta-language-packs channel on Slack.  Your plugin will have a green bar beside it when you push an update to SVN if all is well, otherwise you can see what the error is.

Why is a language not at 100% when translation strings have been submitted?

Translations need to be approved first by a volunteer.  You’ll see them as ‘Waiting’ when you go and view your plugin’s status:

wordpress translations waiting

Once they are approved the percentage should switch to 100%.