テーマやプラグインの.potファイルを作成する方法
WordPressプラグインの開発を終え、世界中に共有したいと考えています。コードは機能し、機能は堅牢で、ドイツの誰かがドイツ語への翻訳方法を尋ねてメールを送ってきました。彼らにlanguagesフォルダーを指し示しますが、そこには何もありません。テンプレートも、文字列も、翻訳者が何を翻訳する必要があるかを知る方法もありません。あなたのプラグインは、技術的には「翻訳準備完了」という名前だけです。
すべての翻訳可能なWordPressプロジェクトは、一つのファイルから始まります。それは**.potテンプレートです。ドイツ語、フランス語、日本語版を誰かが作成する前に、コード内のすべてのユーザー向け文字列をリストしたPOTファイルを作成**する必要があります。このステップをスキップすると、翻訳者はソースコードを一行ずつ読み、どの文字列が表示されるべきかを推測することになります。
このガイドでは、ソースコードの文字列を検出可能にする準備と、3つの異なるツールで.pot自体を生成するという、二つの作業について説明します。WP-CLI、Poedit、そして従来のmakepot/gruntアプローチを使用し、コピーできる実際のコマンドを交えて解説します。最終的には、どんな翻訳者にも渡せるクリーンなテンプレートが完成します。
ステップ1：文字列を翻訳可能としてマークする
POTファイルを作成する前に、ユーザーが目にする可能性のあるすべての文字列をGettext関数で囲む必要があります。スキャナーは認識できる文字列のみを抽出し、これらの関数呼び出しによって文字列を認識します。プレーンな文字列リテラルはスキャナーには見えません。
WordPressには、それぞれわずかに異なるコンテキストに対応するローカライズ関数のファミリーが用意されています。
// Return a translated string
$label = __( 'Add to Cart', 'my-plugin' );
// Echo a translated string directly
_e( 'Your cart is empty', 'my-plugin' );
// Translate with context to disambiguate identical words
$verb = _x( 'Post', 'verb: to publish', 'my-plugin' );
// Translate AND escape for safe HTML output
echo esc_html__( 'Welcome back', 'my-plugin' );
すべての呼び出しの2番目の引数 — 'my-plugin' — はテキストドメインです。これにより、プラグインまたはテーマのすべての文字列が1つの名前空間にまとめられ、WordPressはどの.moファイルをロードすべきかを知ることができます。プロジェクト内のすべての翻訳可能な文字列は、全く同じテキストドメインを共有する必要があります。さもなければ、一部の文字列は翻訳されません。
単語があいまいな場合はいつでも_x()を使用してください。英語の「Post」は名詞にも動詞にもなり、多くの言語で異なる翻訳がされます。コンテキスト文字列を使用すると、翻訳者はそれらを区別できます。また、翻訳された文字列がHTMLに出力される場合は、esc_html__()およびesc_attr__()バリアントを使用することで、安全性とローカライズを同時に確保できます。
文字列を抽出しやすくするためのいくつかの習慣があります。常にプレーンな文字列リテラルを最初の引数として渡してください。変数や__( 'Hello ' . $name, 'my-plugin' )のような連結は決して使用しないでください。スキャナーはソーステキストを静的に読み取り、ランタイム値を解決できないためです。数値を含む文の場合は、複数形が正しくキャプチャされるように_n()を使用し、動的な値を含む文の場合は、文字列を結合するのではなく、%sなどのプレースホルダーの周りにsprintf()を使用してください。ここでの一貫性が、次のステップ（テンプレートの生成）で完全で使いやすい結果を生み出す鍵となります。
ステップ2：ヘッダーでテキストドメインを宣言する
WordPressは、翻訳がどこにあるかを知るために、Text DomainとDomain Pathという2つのヘッダーフィールドを必要とします。これらをプラグインのメインファイルまたはテーマのstyle.cssに設定すると、WordPressはランタイムに適切な.moファイルを自動的にロードします。
<?php
/**
* Plugin Name: My Plugin
* Description: A perfectly localized WordPress plugin.
* Version: 1.0.0
* Requires at least: 6.4
* Text Domain: my-plugin
* Domain Path: /languages
*/
Text Domainは、__()と_e()のすべての呼び出しに渡した文字列（ここではmy-plugin）と一致する必要があります。Domain Pathは、プラグインまたはテーマのルートからの相対パスで、翻訳ファイルが格納されているサブフォルダーをWordPressに伝えます。慣例では/languagesであり、生成された.potファイルはまさにそこに配置されるべきです。
文字列がラップされ、ヘッダーが宣言されていれば、コードはスキャンする準備ができています。プロジェクトを翻訳用に準備するためのより広い視野（自身のものではないテーマを含む）については、「開発者でなくてもWordPressテーマをローカライズする方法」で説明しています。
.potファイルを生成する方法：3つの方法
.potファイルは、ソースコードに対してスキャナーを実行し、すべてのGettext呼び出しを見つけて、文字列をテンプレートに書き込むことで生成します。ここでは、最新の標準的な方法から従来の古い方法まで、信頼性の高い3つの方法を紹介します。
方法1：WP-CLI（推奨）
POTファイルを作成する公式で現代的な方法は、i18nコマンドを使用するWP-CLIです。これはWordPressコアツールの一部として提供され、PHPおよびJavaScriptの文字列を理解し、標準に準拠したテンプレートを1行で生成します。
# Run from your plugin or theme root directory
wp i18n make-pot . languages/my-plugin.pot
# Add a text domain explicitly if auto-detection misses it
wp i18n make-pot . languages/my-plugin.pot --domain=my-plugin
# Scan only specific paths and exclude vendor folders
wp i18n make-pot . languages/my-plugin.pot --exclude=vendor,node_modules
最初の引数はソースディレクトリ（現在のフォルダーの場合は.）、2番目の引数は出力パスです。WP-CLIはファイルを走査し、すべてのラップされた文字列を抽出し、ソースファイルと行番号をコメントとして記録し、.potファイルを書き込みます。これは高速でスクリプト化可能であり、本格的なプロジェクトにとって正しい選択です。
生成されるテンプレートには、追加のフラグで調整できる便利なメタデータが含まれています。--headersを渡すことで、プロジェクト名、バージョン、翻訳者の連絡先アドレスを設定でき、.potヘッダーブロックがプレースホルダーのままではなく、正しく入力されます。WP-CLIはまた、wp_set_script_translations()呼び出しからJavaScript文字列を自動的に抽出し、これはユーザー向けテキストの半分がPHPではなくJavaScriptに存在する現代のブロックテーマやGutenbergプラグインにとって重要です。1つのコマンドで両方の世界をカバーします。
方法2：Poedit（グラフィカル）
デスクトップアプリを好む場合、Poeditはインターフェースを通じてソースコードをスキャンし、テンプレートを生成できます。Poeditを開き、POTから新しい翻訳を作成するか、ソースを直接スキャンするかを選択し、プロジェクトフォルダーを指定し、カタログプロパティの下でソースキーワード（__、_e、_x、esc_html__）を設定します。
Poeditのソーススキャンおよび.pot生成機能はPro版で提供されますが、コマンドを入力するよりもクリックを好む開発者にとって使いやすいワークフローです。これは、続く翻訳フェーズでも優れたエディターとなります。Poeditと他のいくつかのデスクトップオプションについては、「MacとWindowsでPOファイルを編集・翻訳するための無料ツールベスト5」で比較しています。
方法3：makepot / grunt（レガシー）
WP-CLIが登場する前は、WordPress i18n-toolsリポジトリのmakepot.phpスクリプトが標準ツールであり、grunt-wp-i18nを使用してGruntビルドタスクに組み込まれることがよくありました。古いプラグインやテーマでは、今でもこれに出くわすことがあります。
# Legacy makepot.php invocation
php makepot.php wp-plugin /path/to/my-plugin languages/my-plugin.pot
これは機能しますが、WP-CLIに比べてメンテナンスされておらず、セットアップも時間がかかります。すでにそれに依存しているレガシープロジェクトを維持している場合にのみ使用してください。新しいものについては、wp i18n make-potを推奨します。
コードの変更に合わせてテンプレートを更新し続ける
.potファイルは、ある時点での文字列のスナップショットです。機能を追加したり、ラベルを変更したり、表示される文字列のタイプミスを修正したりするたびに、テンプレートは古くなり、翻訳者は新しい文言を見逃してしまいます。
再生をリリースルーティンの一部にしましょう。バージョンを上げる前にwp i18n make-potを再実行し、更新されたテンプレートをwp i18n update-poまたはmsgmergeを使用して既存の翻訳にマージすることで、翻訳者は完成した作業を保持し、新しいギャップのみを確認できます。.potファイルは手動で編集するファイルではなく、再生するビルド成果物として扱ってください。
古いテンプレートは、微妙でフラストレーションのたまる障害を引き起こします。翻訳者が作業した.potファイルには存在しなかったため、「完全に翻訳された」サイトでも新しい文字列が英語で表示されてしまうのです。これを防ぐのは、再生をビルドにスクリプト化するだけで簡単です。これにより、テンプレートがコードから遅れることはありません。一部のチームでは、.potを再生成したときに差分が生じた場合にビルドが失敗するCIチェックを追加し、コミットされたテンプレートが常に現在のソースと一致することを保証しています。
翻訳者が完成した.poファイルを返した後も、それらをWordPressが実際に読み込むバイナリの.moにコンパイルする必要があります。もし、ダウンロード、翻訳、再コンパイルという一連のループをスキップしたいのであれば、クラウドツールがエンドツーエンドで処理できます。SimplePoTranslateはあなたの.potファイルを直接受け入れ、インターフェース内の各文字列の意味を理解するContext-Aware AIで翻訳し、すでにビルドされ命名された**.po、.moなどを含む単一のZIPを返します。そのSyntax Locking**は、%sや%1$sのようなプレースホルダーを固定し、翻訳中に変数が壊れることがありません。
まとめ
正しい方法でPOTファイルを作成するには、まずコードを検出可能にすることです。すべての表示される文字列を__()、_e()、_x()、またはエスケープバリアントで囲み、すべてが同じテキストドメインを共有するようにし、そのドメインとDomain Pathをヘッダーで宣言します。次に、新しいプロジェクトにはWP-CLIを、GUIを好む場合はPoeditを、レガシーコードの維持の場合のみmakepotを使用してテンプレートを生成します。
早く生成し、頻繁に再生し、テンプレートがコードから遅れないようにしましょう。最新の.potファイルがあるかどうかは、プラグインが真に世界に通用するものか、単にそう主張するだけかの違いです。
手動でのコンパイル作業なしで、
.potテンプレートを完成した翻訳に変換する準備はできていますか？SimplePoTranslateを無料で試す — クレジットカードは不要です。無料ティアでテンプレートをアップロードし、数分で出荷可能な翻訳ファイルをダウンロードできます。