WordPress.org 対応の readme.txt と changelog.txt の管理
WordPress.org でのプラグイン配布時、「詳細を表示」モーダルに表示されるコンテンツを国際化・最新化する際に、readme.txt と changelog.txt をどう管理するかをまとめます。
「詳細を表示」モーダルの仕組み
プラグイン管理画面の「詳細を表示」モーダルは、WordPress.org が readme.txt から自動生成します。コード側で i18n 対応をしても、このモーダルには反映されません。
正しいアプローチは、readme.txt を多言語対応させることです。translate.wordpress.org を通じて、自動的に多言語ユーザーへ最新情報が提供されます。
readme.txt の国際化での注意点
Installation セクションの正確性
- インストール対象のディレクトリ名を正確に記載する
- 開発時の仮名（gfm-renderer）ではなく、本番の正式なディレクトリ名（markdown-renderer-for-github）を使う
- ユーザーが実際に参照するため、不正確な情報は致命的
Changelog と Upgrade Notice セクション
- Changelog: 最新バージョンを常に反映。古い情報は削除
- Upgrade Notice: 複数バージョン分の更新通知を記載し、古いバージョンのユーザーも段階的にアップグレードできるように
翻訳登録プロセス
- readme.txt を更新しても、新しい言語パックが自動生成されるわけではない
- translate.wordpress.org で明示的に翻訳を登録し、90% 以上承認される必要がある
- PTE（Project Translation Editor）申請で翻訳承認プロセスを効率化
changelog.txt の標準フォーマット
Keep a Changelog フォーマットに準拠することが重要です。
構成:
[Unreleased]をファイル先頭に配置- バージョンは新しい順（降順）に記載
- Added, Changed, Fixed, Documentation, Testing, Maintenance などのセクションで整理
よくある落とし穴:
- 日本語と英語が混在していないか（WordPress.org 配布対象は英語のみ）
[Unreleased]がファイル下部にないか- エントリの重複がないか
- セクション間の空行が統一されているか
WordPress.org 準拠チェック
npm run lint:wporg で配布対象ファイルの日本語コメントを自動検出するのが有効です。
- readme.txt, changelog.txt に日本語コメントが混ざることがある
- CI/CD パイプラインに lint:wporg を組み込み、リリース前に自動チェック
- テストと組み合わせて品質保証を一体化する
参考リンク
この知見は Markdown Renderer for GitHub の開発過程で得られたものです。