Wakalab Software

English

日本語

English

日本語

Appearance

Managing readme.txt and changelog.txt for WordPress.org ​

When distributing a plugin on WordPress.org, here is how we manage readme.txt and changelog.txt to keep the "View details" modal localized and up to date.

How the "View details" modal works ​

The "View details" modal in the plugins admin screen is generated automatically by WordPress.org from readme.txt. Internationalizing your code (i18n) does not affect this modal.

The right approach is to localize readme.txt itself. Through translate.wordpress.org, up-to-date information is then delivered to users in their language automatically.

Things to watch when localizing readme.txt ​

  1. Accuracy of the Installation section

    • State the install target directory name precisely
    • Use the real production directory name (markdown-renderer-for-github), not a development placeholder (gfm-renderer)
    • Users rely on it to install the plugin, so inaccuracies are fatal

  2. Changelog and Upgrade Notice sections

    • Changelog: always reflect the latest version; remove stale entries
    • Upgrade Notice: include notices for several versions so users on older versions can upgrade gradually

  3. The translation registration process

    • Updating readme.txt does not auto-generate a new language pack
    • You must register the translation explicitly on translate.wordpress.org and reach 90%+ approval
    • Consider a PTE (Project Translation Editor) request to streamline approval

The standard changelog.txt format ​

Following the Keep a Changelog format matters.

Structure:

  • Put [Unreleased] at the top of the file
  • List versions newest-first (descending)
  • Organize into sections like Added, Changed, Fixed, Documentation, Testing, Maintenance

Common pitfalls:

  • Japanese and English mixed together (WordPress.org distribution is English-only)
  • [Unreleased] ending up at the bottom of the file
  • Duplicate entries
  • Inconsistent blank lines between sections

Checking WordPress.org compliance ​

npm run lint:wporg is useful for auto-detecting Japanese comments in distributed files.

  • Japanese comments can slip into readme.txt and changelog.txt
  • Build lint:wporg into the CI/CD pipeline to check automatically before release
  • Combine it with tests to unify quality assurance

References ​

This came out of building Markdown Renderer for GitHub.