How to Prepare and Take Advantage of Language Packs for Plugins Hosted on WordPress.org

---

This is a guest post contributed by Matthew Sparrow who is a young, self-taught developer with minimal coding knowledge that loves to use WordPress. He mostly uses WordPress for personal projects although he has completed a couple of projects for others. In addition to maintaining a few plugins, he’s an active translations contributor.

---

Automatic translations for plugins have been a long time coming. WordPress itself already auto-downloads and auto-updates core translations, so it is a natural progression that plugins and themes will receive the same treatment.

For those who have been following auto plugin translations, it has been in the works for years. It came as a welcome surprise in September when it was announced that plugins will finally be able to have language packs.

If you have a plugin in the WordPress.org directory, then this is important, welcome, and exciting news. However, as great as an initiative as language packs are for plugins, it seems simpler than it actually is.

If you are a plugin developer, you have to go through a few steps in order to get this to work for your plugins. So let’s get started.

Should You Be Excited About Plugin Language Packs?

As a plugin author, I’m really excited about the new translation system, and so should you. The Polyglots team is making it so that you no longer have to include all of your .mo and .po files directly in your plugin. Instead, they will be hosted on WordPress.org.

The ideal scenario is when a user selects their language (either through a new WordPress install or through Settings > General), the language pack for your plugin will be automatically installed and kept updated.

This new system accomplishes a few things:

• Plugin files are smaller. There’s no need to include translation files with your plugin.
• Plugin authors no longer need to manage translations/translators.
• End users are automatically able to see a plugin in their own language assuming a translation has already been created for their locale.

How to Prepare for Plugin Language Packs

Before we jump into translating plugins, you first need to prepare your plugin for it to work with the new translation setup.

In order for you to get your plugin prepared to be moved over to the new system, you need to change your text domain to exactly match your WordPress plugin slug. An important reminder is that even if you have changed your plugin’s name (as Yoast SEO recently did), the slug does not change. For a more in-depth discussion and tutorial, please follow Otto’s great post on language pack prepwork.

You are still welcome to include translation files in your plugin, even with language packs enabled. Translation files in your plugin take priority, and if those aren’t present, that’s where language packs come in.

When you are preparing your plugin for language packs, it is important to note that you should avoid removing translation files from your plugin. If you do so, and your plugin is selected for language packs, your existing translations will not be automatically moved over to the new system.

Do your best to keep your translation files with your plugin until the Polyglots team has informed you that your plugin is ready for language packs.

Wait to Receive the Official Notice

The Polyglot team is preparing the plugins in stages to avoid any major hiccups. Assuming your WordPress.org email is up-to-date, you will receive an email when your plugin is ready.

You may be wondering how long it takes before the team reaches your plugin. There are 40,000+ plugins on WordPress.org, so it is not a quick process. WordPress is preparing plugins in batches according to the amount of active installs each plugin has.

If your plugin has over 30,000+ active installs, then chances are you are on the new system, although I’ve seen plugins with 10,000+ active installs also be approved.

Unfortunately, there is no way to make the process quicker. Please practice patience and eventually your turn will come.

You’ve Received the E-Mail That Your Plugin Is Ready

So you finally receive the email saying that your plugin is going to be uploaded with language pack support. Awesome! This is what the email that I received looks like. Note that I’m using one of my approved plugins as an example.

Howdy!
​
We’re emailing you because you’re an author for the following plugin on WordPress.org:
​
* Easy Updates Manager : https://wordpress.org/plugins/stops-core-theme-and-plugin-updates/
​
Next week, we intend to import the plugin listed above into the translate.wordpress.org translation system. Language packs will also be enabled for your plugin, for any locales that are fully translated (at 100%).
​
As part of this process, all of the strings in your plugin will be imported into translate.wordpress.org. Additionally, any language files that you ship with your plugin (‘mo’ files) will be imported and synced with their respective locales within translate.wordpress.org.
​
No strings in your plugin? Plugin translations include the ability to translate the readme and display these translations in the localized WordPress.org plugin directories.

If you have prepared your plugin already then this notice is of no real importance. If you have not yet prepared your plugin and you have received the notice then you need to prepare your plugin ASAP. If you don’t prepare your plugin then… well… I don’t really know, but it won’t be good. So go and prepare your plugin if you have not yet done so.
…

Your Plugin Is Semi-Ready for Language Packs. Now What?

A week or so after you receive the notice, your plugin and its translations are moved to translate.wordpress.org. You will likely not receive a notice when your plugin is moved.

To find out if it’s been uploaded, visit your plugin’s WordPress.org page where you should see a translations section in the right sidebar. Click the Translate Plugin Name button. If you are brought to a page that looks like the one below then your plugin is uploaded and is ready to be translated.

If you see a page that looks different from this (i.e., a Not Found error), your plugin is not yet ready.

Assuming you’ve received the e-mail, your plugin is ready, and you’ve waited a reasonable amount of time, you should be good to go as far as preparing your plugin.

If it has been over two weeks and your plugin has not yet been uploaded, you should contact the Polyglot team on their blog, or in the #polyglots channel on WordPress Slack. Please exercise extreme patience as the process can take a week or sometimes even two.

Removing Your Translation Files From Your Plugin

Now that your plugin is uploaded to the system, you can safely remove the translation files from your plugin. If you don’t have any .mo and .po files in your plugin, then you can skip this step.

One thing to note: You may not want to remove your translation files if your plugin does not have any translations on translate.wordpress.org or translations are not 100% complete.

Making Your Plugin Translatable

With all of that stuff out-of-the-way, it’s time to focus on translating your plugin. This is where it can get confusing but try to stick with me.

By default, you cannot submit translations for your plugin in any language. Because of this, you need to ask the Polyglots team to add you as a translator for your plugin. You can do so by heading over to the Polyglots blog and ask them. To make it easier they came up with a template of what to say.

Hello Polyglots!

I am the plugin author for [plugin-name and link to plugin directory]. We have a number of great translation editors that we’d like to be able to approve translation for our plugin(s). Please add the following WordPress.org users as translation editors for their respective locales:
o #ar – @username
o #bn – @username, @username
o #da – @username
o #de-ch – @username
etc…

If you have any questions, just comment here. Thank you!

Ideally, the above will include requests for multiple plugins, but as plugins are being rolled out slowly, it’s acceptable at the moment to include one request per plugin.

Make sure that you use WordPress.org usernames and that the user is still active. If you are wondering what languages there are, you can visit https://translate.wordpress.org/ and scroll through the different languages that WordPress supports.

Please only ask to be added as a translator for the languages you know. You will not be approved if you are not a native speaker for a language.

At this point, again, patience is needed. The Polyglot team will receive your request and will work through it. If your post doesn’t show up right away, it’s because first-time posters are moderated.

In a week or two, the translators you requested should be added to your plugin. If there are any issues, a Polyglot member will comment on your request with any difficulties encountered or notify you that they have approved your request.

You’ll know when you are added when you see new badges appear on your WordPress.org profile page. One is a translation editor badge and the other is a translation contributor badge.

How Do I Translate?

First, visit https://translate.wordpress.org/, select your language, then click the plugins tab. Search for your plugin and then click the translate project button. You’ll be brought to a page that looks like the one below. This page is where you can translate your plugin. In this case, my plugin is already translated in the language that I selected.

On this table, there are four separate things to translate. Trunk, the stable release (version), and the readme.txt variations. In order for language packs to work, you need to translate all four versions.

To translate, click on one of the sub-projects. This takes you to the translation page. Here, you can see all of the different strings that need to be translated in your plugin. You can edit a string by clicking the details button, translating it in the text editor, and then clicking the add translations button.

Even if you’re not added as an editor for a language, you can still translate a plugin. The only difference is instead of adding the translations directly, you can only request that it be changed. Someone from the Polyglots team will need review and approve your translation suggestions.

Once Your Translations Are Ready

Once you’ve finished translating a language completely, it will be available for people to use. However, it doesn’t become available immediately. It can take one to three days for a translation to be available once you finish it. Again, exercise patience.

You’ll know when the translation is available when you see it in the translation section on your WordPress.org plugin’s page. For example, you can see what it looks like in the picture below.

Also, you’ll know it’s working if you go into a website (preferably not a live website), download your plugin, and select the language that you want to test in Settings > General.

Plugin Language Packs Are Here to Stay

Getting language packs to work properly in WordPress plugins is not exactly a straightforward process, which is precisely why plugins are being rolled out slowly.

Please remember that everyone is a volunteer, from the Polyglots team, to translators, and to the plugin authors. Please give props where appropriate as everyone is working hard to make plugin language packs the norm.

If you are having any trouble, the Polyglots team also has a handbook available which provides some good information on how this new system works.

I’ll also do my best to answer any questions in the comment section. If you have additional insight, please weigh in as well.