A client came to us recently, sure that something in their code was broken. They had spent months on the plugin, submitted it to the directory, and watched it get bounced twice. They went hunting for an obscure bug, maybe a conflict with a core hook. The cause was the English readme requirement.
They had written a quick readme.txt in their own language and run it through a free online translator, figuring that was good enough for the WordPress plugin review team. It was not. The plugin code was solid, and a single text file still stopped it twice.
The file the review team reads first
It is easy to spend all your attention on the PHP, the JavaScript and the database queries. Documentation ends up as an afterthought, and I did the same thing early in my career: my first instinct with this client was to go look at their custom post types and their REST API endpoints. But the readme.txt does real work. It is what people read on the wordpress.org listing, and it is the source text that every later translation is built from. The WordPress plugin review team set the rule out in a post on make.wordpress.org/plugins: your readme.txt must be in English.
The reviewers come from all over the world, so English is the language they have in common. A readme in another language, or one that has been badly machine translated, delays your plugin and turns the review into extra back and forth with the team. It also reads as careless.
The English text is not only for the review. It is also the base for translate.wordpress.org. Translators work from your source file, so a rough English readme.txt produces a rough German, Spanish or Japanese version of it, and every reader who opens your plugin page in their own language sees that instead.
Writing a compliant readme.txt for a WordPress plugin
The format is already documented. Follow the WordPress readme standard and write each section in plain English so a user or a reviewer can tell what the plugin does. A basic structure looks like this:
=== Bbioon Awesome Plugin ===
Contributors: bbioonteam
Donate Link: https://bbioon.com/donate
Tags: awesome, utility, tools
Requires at least: 5.8
Tested up to: 6.5
Stable tag: 1.0.0
Requires PHP: 7.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
A short description of the plugin.
== Description ==
This is where the detailed description goes. Explain what your plugin does, its main features, and why someone should use it. Make sure this is clear, concise, and in proper English. Use **bbioon_plugin_function()** for clarity.
== Installation ==
1. Upload the entire `bbioon-awesome-plugin` folder to the `/wp-content/plugins/` directory.
2. Activate the plugin through the 'Plugins' menu in WordPress.
3. Configure settings via the **Bbioon Settings** menu.
== Frequently Asked Questions ==
= Does this plugin work with all themes? =
Yes, **bbioon_plugin_init()** is designed to be theme-agnostic.
= How do I use the [bbioon] shortcode? =
Simply insert `[bbioon_shortcode]` into your posts or pages.
== Changelog ==
= 1.0.0 =
* Initial release of the **Bbioon Awesome Plugin**.
* Added **bbioon_admin_notice** filter.
== Upgrade Notice ==
= 1.0.0 =
Initial release.
Every section is in English, including the description and the FAQ answers. That does make the review team’s job easier, but the bigger payoff is that anyone who lands on your plugin page can work out what it does before installing it.
What to do before you submit
Write the readme.txt in English and treat it as part of the plugin rather than a file you fill in on submission day. It keeps the review short, it gives translators something usable to start from, and it keeps your listing consistent with the rest of the Plugin Directory.
This stuff gets complicated fast. If you are tired of debugging someone else’s mess and just want your site to work, drop my team a line. We have probably seen it before.
