DocsWP — WordPress Help

Plugin/Theme Authors Guide

Interested in getting your project translated? This page will show you, as the theme or plugin author, some tips for working with translators in the Polyglot community.

If you are looking for a technical localization guide, please see the meta and plugin handbooks.

If you are looking to request PTE status, please see Project Translation Editor Request.

Internationalizing Your Project

In general, it’s helpful to keep in mind that the Polyglots team is more focused on localization than internationalization. However, in order for community members to be able to translate your plugin or theme, you will need to make sure that it’s set up properly.

A good place to start are the Meta and Plugin Handbooks, which both contain information on how to internationalize your project.

Error: Not properly prepared for localization

If there are any issues with the internationalization of your plugin or theme, you may come across the following error:

This plugin is not properly prepared for localization (View detailed logs on Slack). If you would like to translate this plugin, please contact the author.

If you are seeing the message above on your translation status page, make sure to follow the links and fix the issues.

If you have difficulties in locating the exact error, drop a message in #polyglots and we’ll help you.

Getting Your Project Translated 

There are a number of ways to have your project translated. Most can be divided between volunteer-based translations (in other words, contributions from community members) or through paid translators.

We DO NOT accept unreviewed machine translations. Please don’t submit translations that are not reviewed by a human who is a fluent speaker of the language.

Using translate.wordpress.org

All translations take place using GlotPress, via translate.wordpress.org. For more information on how translations work via this platform, please visit the translate.wordpress.org Handbook page.

Using your own translation team

If your company has a paid team of translators that you would like to manage the bulk of your translations, please visit the PTE Request by a Plugin/Theme Author guide to understand your options.

Inspiring community contributions

There are a few ways you can encourage active users of your project to help with translating your plugin or theme. In fact, if you have a loyal base of users, you might even find that some of them have already started translating your project, without your knowing!

If you would like to encourage others to help with translations, it is recommended to:

  1. Add a sticky topic on your support forum letting users know that you’re looking for translation contributors.
  2. Add instructions and the call for volunteers into your readme.txt.
  3. Add it inside your plugin as a (preferably dismissable) banner message on the plugin settings page. (PRO tip: in this case, your code could even take into account which language the current user has selected for their admin pages! Think of saying something like Can you help me translate this plugin to %s?

We recommend linking to our How to translate page in your invitation so that the contributors will be able to learn our proper processes.

Checking the Translation Status

When translations are added by a user who has no validation rights on the translate.wordpress.org platform, the status is set to “Waiting”.

Unless translations are reviewed by a PTE or GTE and set to “Current” status, a language pack will not be created/updated.

You can check the translation status of your project by going to a page like these:

Getting “Waiting” Translations to “Current” (approved)

In order for the initial language pack to be created for your plugin/theme, at least 90% of the strings need to be in “Current” status (for plugins, 90% of the Stable sub-projects).

Although GTEs can do this validation, their available time for volunteer contributions is usually limited. Therefore, they typically prefer vetting and mentoring individual translation contributors (who know the target language), and making the latter a PTE when they’re ready. You can submit a PTE request to ask a locale team to check pending strings from a user and consider that user as translation editor.

Project Translation Editor (PTE) Request

If you are interested in learning more about how translations get approved and deployed, please refer to the How to translate page.

Once Your Project is Translated

Once a language pack has been created for your plugin or theme, it will automatically appear in the related plugin or theme directory on each locale’s Rosetta site. Users in this locale will be able to search for your plugin or theme in the same way as usual, just in their own language.

Since WordPress 4.7, users will automatically get community contributed translations from https://translate.wordpress.org/, these take precedence over any translation you may be distributing with your plugin/theme and loading with load_plugin_textdomain() or load_theme_textdomain(), unless you’re breaking this in any way, e.g. by using a different textdomain than your plugin/theme slug.

If you’re distributing a translation with your plugin/theme in this way, once the first language pack for a locale has been generated on the repo, then you may want to consider removing the corresponding translation from your distribution.

Following up the status for translations and language packs of your plugin/theme

When the strings from a new version of a plugin or theme are imported, and when language packs are created, log entries are added to the Slack channel meta-language-packs. You can search for the project slug of your plugin/theme to find more details about the processing for your project.

Also note that you via a drop-down on the main translation page for your plugin/theme can reach a list of the currently existing language packs and a list of language contributors.

Using professional translators for your plugin/theme

If you’re using professional translators for your plugin/theme, then you may consider using the special role CLPTE (Cross-Locale PTE). This role is only meant as a way to import and use translations you have obtained from professional, duly instructed translators. Read more at https://make.wordpress.org/polyglots/handbook/about/roles-and-capabilities/#cross-locale-project-translation-editor

External resources