ユーティリティ(文字列・日時ほか)の記事一覧|WordPressの専門家が作る教科書 https://wordpress.ks-product.com WordPressを活用したウェブサイトの制作方法を教えます Thu, 08 Oct 2026 14:27:53 +0000 ja hourly 1 https://wordpress.org/?v=7.1.5 WordPress の _e() と __() の違い|esc_html_e・esc_attr__ との使い分け https://wordpress.ks-product.com/3173/ Thu, 15 Oct 2026 23:00:00 +0000 https://wordpress.ks-product.com/?p=3173 結論

WordPress の _e() と __() の違いは、出力するか、返すかだけです。

  • __( 'テキスト', 'ドメイン' ): 翻訳した文字列を返す。変数に入れたり、他の関数に渡したりするときに使う。
  • _e( 'テキスト', 'ドメイン' ): 翻訳した文字列をその場で echo する。戻り値はない(WordPress 1.2.0 から)。

ただし、どちらもエスケープはしません。_e() のリファレンスも「_e() はエスケープ関数ではない」とし、esc_html_e() を使うよう勧めています。実務では次のように選ぶのが安全です。

場面 使う関数
HTML の本文として出力 esc_html_e()
HTML の本文用の文字列を返す esc_html__()
属性値(title・alt・placeholder など)に出力 esc_attr_e() / esc_attr__()
変数を埋め込む printf( esc_html__( '... %s ...', 'domain' ), esc_html( $var ) )
同じ英語で意味が違う語 _x()
単数・複数で変わる語 _n()

原因・仕組み

__() は内部で translate() を呼び、テキストドメインに対応する読み込まれた翻訳ファイルから訳を探して返します。_e() はその結果を echo するだけの関数です。

訳文は翻訳ファイルや gettext フィルターで外から差し替えられる値です。翻訳者や他のプラグインが HTML を混ぜた場合、_e() はそれをそのまま出力します。esc_html_e() は「翻訳 → エスケープ → 出力」を1回で行うので、echo esc_html( __( ... ) ) と同じ結果になります。

Common APIs Handbook も、HTML タグの属性で使う翻訳文字列はエスケープしなければならないとし、esc_html__()・esc_html_e()・esc_attr__()・esc_attr_e() を挙げています。

手順(サンプルコード)

基本の使い分け

<h2><?php esc_html_e( 'Related posts', 'wl1' ); ?></h2>

<input type="search" placeholder="<?php esc_attr_e( 'Search…', 'wl1' ); ?>">

<?php
$label = esc_html__( 'Read more', 'wl1' ); // 変数に入れるときは「返す」版
echo '<a href="' . esc_url( get_permalink() ) . '">' . $label . '</a>';

変数を埋め込む

/* translators: %s: user name */
printf( esc_html__( 'Hello, %s', 'wl1' ), esc_html( $name ) );

Plugin Handbook は、_e( "Your city is $city.", ... ) のように変数を文字列の中に直接書くのは誤りで、printf() とプレースホルダーを使うよう説明しています。翻訳者向けのコメントは translators: で始め、翻訳関数の直前の最後の PHP コメントにします。

HTML を含めたい場合

訳文に <strong> などを含めたいときは、esc_html 系ではなく wp_kses() で許可するタグを絞ります。

echo wp_kses(
    __( 'Read the <strong>terms</strong> first.', 'wl1' ),
    array( 'strong' => array() )
);

動作確認(検証環境と結果)

WordPress 7.1.2(ja、ロケール ja)、PHP 8.2.12 の CLI 検証環境で実行しました。

  • __( 'Posts' ) の戻り値は '投稿'。_e( 'Posts' ) は 投稿 を出力し、戻り値は NULL だった。
  • _x( 'Post', 'post type singular name' ) は 投稿。
  • gettext フィルターで、wl1 ドメインの Read more の訳を 続きを読む<script>alert(1)</script> に差し替えて比較した結果:
  • _e() → 続きを読む<script>alert(1)</script>(そのまま出力)
  • esc_html_e() → 続きを読む&lt;script&gt;alert(1)&lt;/script&gt;
  • esc_attr__() → 同じくエスケープされ、title="..." の中でも属性が壊れなかった
  • printf( esc_html__( 'Hello, %s', 'wl1' ), esc_html( '<b>佐藤</b>' ) ) は Hello, &lt;b&gt;佐藤&lt;/b&gt; になった(翻訳ファイルがないため英語のまま)。
  • 「HTML を含めたい場合」のコードに <script>x</script> を足して試すと、出力は Read the <strong>terms</strong> first.x で、strong だけが残り script タグは除去された。

ログは testse-vs-translate-esc-html-e-difference.md にあります。

WordPress の _e と __ の違いの注意点

  • テキストドメインには、変数や定数ではなく文字列そのものを書きます(Plugin Handbook)。翻訳文字列を抽出するツールが、ソースコードを静的に読むためです。
  • テーマのテキストドメインは style.css の Text Domain と一致させます(WordPress テーマ自作の手順|最小構成(style.css・index.php)から作る方法)。
  • 第2引数を省略すると default(WordPress 本体)のドメインになり、コアの訳が使われます。自作の文字列で省略すると、意図しない訳が付くことがあります。
  • __() の結果を echo するなら、最初から esc_html_e() にまとめた方が漏れがありません。

WordPress の _e と __ の違いでよくあるミス

  • echo __( ... ) や _e( ... ) をエスケープせずに使う。
  • 属性値の中で esc_html_e() を使う(属性値には esc_attr_e())。
  • _e() の戻り値を変数に入れようとして、空になる。
  • 訳文の中に変数を直接書き、翻訳ファイルに登録できない文字列になる。

WordPress の _e と __ の違いのチェックリスト

  • 出力するのか、返すのかで _e 系 / __ 系を選んだ
  • 本文は esc_html、属性は esc_attr の付いた関数にした
  • 変数は printf() とプレースホルダーで埋め込んだ
  • テキストドメインは文字列リテラルで、テーマ・プラグインと一致している
  • 必要な箇所に translators: コメントを付けた

WordPress の _e と __ の違いのFAQ(よくある質問)

Q. 日本語サイトしか作らないのに翻訳関数は必要ですか?
A. 必須ではありません。ただし配布テーマ・プラグインや、管理画面の文言を他のコードから変えられるようにしたい場合は使います。使わないなら、日本語を esc_html() で出力すれば十分です。

Q. esc_html_e() だけで HTML を出せますか?
A. 出せません。タグもエスケープされます。HTML を含めるなら wp_kses() を使います。

Q. JavaScript の文字列は?
A. __()・_x()・_n() は JavaScript 版(wp.i18n)もあります(Common APIs Handbook)。

筆者の見解(WordPress の _e と __ の違い)

_e() と __() の違いそのものは単純ですが、実際に問題になるのはエスケープの有無だと考えます。私は、テーマやプラグインのテンプレートでは _e() と echo __() を原則使わず、esc_html_e()・esc_attr_e() を既定にするのが、レビューの手間も減って現実的だと思います。訳文は外から変えられる入力の一つ、と捉えておくと判断を誤りにくいです。

WordPress の _e と __ の違いの関連項目

出典(一次情報)

]]>
wp_parse_slug_list() の使い方|説明・引数・注意点 https://wordpress.ks-product.com/2916/ https://wordpress.ks-product.com/2916/#respond Sat, 03 Oct 2026 12:27:21 +0000 https://wordpress.ks-product.com/?p=2916 説明

wp_parse_slug_list() は、カンマ(や空白)区切りの文字列や、配列を、スラッグの配列に整える関数です。各要素は、sanitize_title() で整えられ、重複は取り除かれます。

基本構文

wp_parse_slug_list( array|string $input_list ): string[]

引数

  • $input_list:スラッグの一覧(カンマ区切りの文字列、または配列)

戻り値

整えられたスラッグの配列。

使い方(サンプル)

$slugs = wp_parse_slug_list( 'news, event, news' );
// array( 'news', 'event' )

注意点

  • 各要素は、小文字・ハイフン区切りに整えられます。
  • 重複は、取り除かれます。
  • キーが連番にならない場合があり、空文字が混じることもある。必要なら array_values() を通す。

実務での使いどころ

  • ショートコードの属性(categories="news,event")を、スラッグの配列にして、使うとき。

よくあるミスと対策

  • explode() だけで分けて、空白や大文字が、そのまま残る。
  • 数値のIDの一覧を整えたいのに、使っている。IDには wp_parse_id_list()。

NG例

$slugs = explode( ',', $atts['categories'] ); // 空白や大文字が、そのまま残る

OK例

$slugs = wp_parse_slug_list( $atts['categories'] );

使い分け早見表

関数 整える対象
wp_parse_slug_list() スラッグの一覧
wp_parse_id_list() IDの一覧
sanitize_title() 1つのスラッグ

関連項目

wp_parse_id_list()、sanitize_title()

公式リファレンス:wp_parse_slug_list() | WordPress Developer Resources

]]>
https://wordpress.ks-product.com/2916/feed/ 0
get_user_locale() の使い方|説明・引数・注意点 https://wordpress.ks-product.com/2914/ https://wordpress.ks-product.com/2914/#respond Sat, 03 Oct 2026 12:27:19 +0000 https://wordpress.ks-product.com/?p=2914 説明

get_user_locale() は、ユーザーの言語(プロフィールで選んだ言語)を取得する関数です。設定がなければ、サイトの言語を返します。

基本構文

get_user_locale( int|WP_User $user = 0 ): string

引数

  • $user:ユーザーのIDまたはオブジェクト(省略すると、現在のユーザー)

戻り値

ロケールの文字列。

使い方(サンプル)

$locale = get_user_locale();

注意点

  • ユーザーが、言語を選んでいないときは、サイトの言語になります。
  • そのリクエストで使う言語を、判定するときは、determine_locale()。

実務での使いどころ

  • 管理画面で、ユーザーの言語に合わせて、表示を変えるとき。
  • メール通知を、ユーザーの言語で、送るとき。

よくあるミスと対策

  • サイトの言語を使うべき場面で、使っている(表示言語が、人によって変わる)。
  • ログインしていないときの動作を、考えていない。

NG例

$locale = get_locale(); // ユーザーの言語のつもり

OK例

$locale = get_user_locale( $user_id );

使い分け早見表

関数 返す言語
get_user_locale() ユーザーの言語
get_locale() サイトの言語
determine_locale() そのリクエストで、使うべき言語

関連項目

get_locale()、determine_locale()

公式リファレンス:get_user_locale() | WordPress Developer Resources

]]>
https://wordpress.ks-product.com/2914/feed/ 0
determine_locale() の使い方|説明・引数・注意点 https://wordpress.ks-product.com/2912/ https://wordpress.ks-product.com/2912/#respond Sat, 03 Oct 2026 12:27:16 +0000 https://wordpress.ks-product.com/?p=2912 説明

determine_locale() は、そのリクエストで、使うべき言語(ロケール)を取得する関数です。管理画面では、ユーザーの言語になります。ログイン画面では、言語の選択(wp_lang)があればその言語、なければ、サイトの言語になります。

基本構文

determine_locale(): string

引数

引数はありません。

戻り値

ロケールの文字列(ja・en_US など)。

使い方(サンプル)

$locale = determine_locale();
if ( 'ja' === $locale ) {
	// 日本語
}

注意点

実務での使いどころ

  • 翻訳ファイルを、読み込むときに、今の言語を、判定するとき。
  • サイトの言語と、ユーザーの言語の、どちらを使うべきか、迷うとき。

よくあるミスと対策

  • サイトの言語を使うべき場面で、ユーザーの言語を使っている(または、その逆)。
  • 言語コードの形式を、決め打ちしている。

NG例

if ( 'ja_JP' === determine_locale() ) { // 日本語のロケールは、ja
	// ...
}

OK例

if ( 0 === strpos( determine_locale(), 'ja' ) ) {
	// 日本語
}

使い分け早見表

関数 返す言語
determine_locale() そのリクエストで、使うべき言語
get_locale() サイトの言語
get_user_locale() ユーザーの言語

関連項目

get_locale()、get_user_locale()、load_theme_textdomain()

公式リファレンス:determine_locale() | WordPress Developer Resources

]]>
https://wordpress.ks-product.com/2912/feed/ 0
__() の使い方|説明・引数・注意点 https://wordpress.ks-product.com/2908/ https://wordpress.ks-product.com/2908/#respond Sat, 03 Oct 2026 12:27:10 +0000 https://wordpress.ks-product.com/?p=2908 説明

__() は、文字列を翻訳して、値として返す関数です。テーマやプラグインの、翻訳できる文字列に使います。出力する関数は _e()。

基本構文

__( string $text, string $domain = 'default' ): string

引数

  • $text:翻訳する文字列(原文)
  • $domain:テキストドメイン(翻訳ファイルの識別名)

戻り値

翻訳された文字列。翻訳がないときは、原文を返します。

使い方(サンプル)

$label = __( '送信する', 'my-plugin' );
echo esc_html( $label );

注意点

  • 出力しません。値を返すだけです。
  • エスケープは、行われません。HTMLに出力するときは、esc_html__() や、esc_html() を通します。
  • テキストドメインは、変数ではなく、文字列で直接書きます。

実務での使いどころ

  • 翻訳できる形で、ボタンの文字や、見出しを、変数に入れて使うとき。
  • sprintf() と組み合わせて、数値を含む文を、翻訳するとき。

よくあるミスと対策

  • エスケープせずに、そのまま出力している。
  • テキストドメインや原文を、変数にしている。翻訳ファイルを作るときに、文字列を抽出できない。
  • 翻訳する文を、連結で作っている。1つの文として、書く。

NG例

echo __( $label, $domain ); // 変数で、翻訳を抽出できない。エスケープもない

OK例

echo esc_html( __( '送信する', 'my-plugin' ) );
// 数値を含む文: sprintf( __( '%d件の結果', 'my-plugin' ), $count )

使い分け早見表

関数 役割
__() 翻訳して、値を返す
_e() 翻訳して、出力する
esc_html__() 翻訳して、エスケープして、値を返す
_x() 文脈つきで、翻訳して、値を返す

関連項目

_e()、esc_html_e()、_x()、_n()

公式リファレンス:__() | WordPress Developer Resources

]]>
https://wordpress.ks-product.com/2908/feed/ 0
restore_current_blog() の使い方|説明・引数・注意点 https://wordpress.ks-product.com/2499/ https://wordpress.ks-product.com/2499/#respond Sat, 03 Oct 2026 08:26:47 +0000 https://wordpress.ks-product.com/?p=2499 説明

restore_current_blog() は、switch_to_blog() で切り替えたあとに、1つ前のサイトへ戻す関数です。

基本構文

restore_current_blog(): bool

引数

引数はありません。

戻り値

戻せたときは true。切り替えの履歴がないときは false。

使い方(サンプル)

switch_to_blog( 2 );
// 別のサイトでの処理
restore_current_blog();

注意点

  • switch_to_blog() を呼んだ回数だけ、呼ぶ必要がある。
  • 切り替えの履歴がないときに呼ぶと、false を返す。

実務での使いどころ

  • switch_to_blog() で別のサイトを処理したあとに、必ず元に戻すとき。

よくあるミスと対策

  • switch_to_blog() を2回呼んだのに、1回しか戻していない。
  • 途中の return や例外で、戻す処理が飛ばされる。try・finally を使う。

NG例

switch_to_blog( 2 );
if ( ! $ok ) {
	return; // 元に戻していない
}
restore_current_blog();

OK例

switch_to_blog( 2 );
try {
	// 別のサイトでの処理
} finally {
	restore_current_blog();
}

使い分け早見表

関数 役割
switch_to_blog() 別のサイトへ切り替える
restore_current_blog() 切り替え前のサイトへ戻す
get_current_blog_id() 現在のサイトのID

関連項目

switch_to_blog()、get_current_blog_id()、is_multisite()

公式リファレンス:restore_current_blog() | WordPress Developer Resources

]]>
https://wordpress.ks-product.com/2499/feed/ 0
switch_to_blog() の使い方|説明・引数・注意点 https://wordpress.ks-product.com/2497/ https://wordpress.ks-product.com/2497/#respond Sat, 03 Oct 2026 08:26:45 +0000 https://wordpress.ks-product.com/?p=2497 説明

switch_to_blog() は、マルチサイトで、処理の対象を別のサイトに切り替える関数です。切り替えたあとは、restore_current_blog() で元に戻します。

基本構文

switch_to_blog( int $new_blog_id, bool $deprecated = null ): true

引数

  • $new_blog_id:切り替え先のサイトのID

戻り値

常に true を返します。

使い方(サンプル)

switch_to_blog( 2 );
$posts = get_posts( array( 'numberposts' => 5 ) );
restore_current_blog();

注意点

  • 切り替えたあとは、必ず restore_current_blog() で元に戻す。
  • 切り替えのたびに、設定やキャッシュの読み替えが行われるため、処理が重い。ループの中で、何度も呼ばない。

実務での使いどころ

  • ネットワーク内の、別のサイトの投稿や設定を読み取るとき。
  • メインサイトから、各サブサイトへ、設定を配るとき。

よくあるミスと対策

  • restore_current_blog() を呼ばず、以降の処理が、別のサイトのままになる。
  • ループの中で何度も切り替え、処理が遅くなる。
  • 切り替え先のサイトのプラグインやテーマの関数が、使えると思っている。切り替わるのは、データベースのテーブルや設定などで、読み込まれているコードは変わらない。

NG例

switch_to_blog( 2 );
$title = get_bloginfo( 'name' ); // 元に戻していない

OK例

switch_to_blog( 2 );
$title = get_bloginfo( 'name' );
restore_current_blog();

使い分け早見表

関数 役割
switch_to_blog() 別のサイトへ切り替える
restore_current_blog() 切り替え前のサイトへ戻す
get_current_blog_id() 現在のサイトのID

関連項目

restore_current_blog()、get_current_blog_id()、is_multisite()

公式リファレンス:switch_to_blog() | WordPress Developer Resources

]]>
https://wordpress.ks-product.com/2497/feed/ 0
get_current_blog_id() の使い方|説明・引数・注意点 https://wordpress.ks-product.com/2495/ https://wordpress.ks-product.com/2495/#respond Sat, 03 Oct 2026 08:26:43 +0000 https://wordpress.ks-product.com/?p=2495 説明

get_current_blog_id() は、現在のサイトのIDを取得する関数です。マルチサイトで使います。

基本構文

get_current_blog_id(): int

引数

引数はありません。

戻り値

サイトのID(整数)。マルチサイトでない環境では 1。

使い方(サンプル)

$site_id = get_current_blog_id();
$key     = 'my_cache_' . $site_id;

注意点

  • switch_to_blog() で切り替えたあとは、切り替え先のサイトのIDを返す。
  • マルチサイトでない環境では、1 を返す。

実務での使いどころ

  • サイトごとに、設定やキャッシュのキーを分けるとき。
  • switch_to_blog() の前後で、現在のサイトを確認するとき。

よくあるミスと対策

  • サイトのIDと、ネットワークのIDを取り違える。
  • switch_to_blog() のあとに呼び、切り替え先のIDになることを忘れる。

NG例

$key = 'my_cache'; // ネットワーク共通の場所に保存すると、サイトごとに分かれず、混ざる

OK例

$key = 'my_cache_' . get_current_blog_id();

使い分け早見表

関数 取得・実行するもの
get_current_blog_id() 現在のサイトのID
switch_to_blog() 別のサイトへ切り替える
is_main_site() メインサイトか判定する

関連項目

switch_to_blog()、restore_current_blog()、is_multisite()

公式リファレンス:get_current_blog_id() | WordPress Developer Resources

]]>
https://wordpress.ks-product.com/2495/feed/ 0
wp_filter_object_list() の使い方|説明・引数・注意点 https://wordpress.ks-product.com/523/ https://wordpress.ks-product.com/523/#respond Fri, 02 Oct 2026 16:00:53 +0000 https://wordpress.ks-product.com/523/ 説明

wp_filter_object_list() は、配列から条件に合う要素を抽出し、必要なフィールドだけを返す関数です。

基本構文

wp_filter_object_list( array $input_list, array $args = array(), string $operator = "and", string|false $field = false ): array

引数

  • $input_list:対象の配列
  • $args:条件
  • $operator:論理演算子(and / or / not)
  • $field:取り出すフィールド

戻り値

抽出結果。

使い方(サンプル)

$list = wp_filter_object_list( $items, array( 'type' => 'a' ) );

注意点

  • wp_list_filter() と wp_list_pluck() を組み合わせた処理です。

実務での使いどころ

  • オブジェクトの一覧を、条件で絞り込み、さらに、1つの項目だけを取り出すとき。

よくあるミスと対策

  • 項目($field)を指定しないと、絞り込んだ、オブジェクトの一覧が返る。
  • キー(添字)が、保持される。
  • 条件の項目が、存在しない要素は、除外される。

NG例

$names = wp_filter_object_list( $terms, array( 'parent' => 0 ) ); // オブジェクトの一覧が返る

OK例

$names = wp_filter_object_list( $terms, array( 'parent' => 0 ), 'and', 'name' );

使い分け早見表

関数 役割
wp_filter_object_list() 絞り込みと、項目の取り出しを、まとめて行う
wp_list_filter() 条件に合う要素だけを、残す
wp_list_pluck() 1つの項目だけを、取り出す

関連項目

wp_list_filter()、wp_list_pluck()

公式リファレンス:wp_filter_object_list() | Function | WordPress Developer Resources

]]>
https://wordpress.ks-product.com/523/feed/ 0
wp_doing_ajax() の使い方|説明・引数・注意点 https://wordpress.ks-product.com/521/ https://wordpress.ks-product.com/521/#respond Fri, 02 Oct 2026 16:00:15 +0000 https://wordpress.ks-product.com/521/ 説明

wp_doing_ajax() は、現在のリクエストがAjaxかを判定する関数です。

基本構文

wp_doing_ajax(): bool

引数

引数はありません。

戻り値

Ajaxなら true。

使い方(サンプル)

if ( wp_doing_ajax() ) {
	return;
}

注意点

  • is_admin() はAjaxでも true になるため、区別したいときに使います。

実務での使いどころ

  • Ajaxの処理(admin-ajax.php)の中かを、判定するとき。
  • is_admin() が、Ajaxでも true になるため、Ajaxだけを、区別したいとき。

よくあるミスと対策

  • is_admin() で、Ajaxを判定している。管理画面のページと、区別できない。
  • REST APIの判定に、使っている。REST APIは、別の仕組み。

NG例

if ( is_admin() ) {
	// 管理画面のページだけのつもり(Ajaxでも入る)
}

OK例

if ( is_admin() && ! wp_doing_ajax() ) {
	// 管理画面のページだけ
}

使い分け早見表

関数 判定するもの
wp_doing_ajax() Ajax(admin-ajax.php)か
is_admin() 管理画面(Ajaxも含む)か
wp_is_json_request() JSONを期待するリクエストか

関連項目

is_admin()、wp_is_json_request()

公式リファレンス:wp_doing_ajax() | Function | WordPress Developer Resources

]]>
https://wordpress.ks-product.com/521/feed/ 0