WordPress: __()や_e()だけじゃない。翻訳関数の一覧

WordPressには__()や_e()などの翻訳機能があります。
調べてみるとこれ以外にもあるようです。
そこでソースコードから抜き出してみました。

翻訳関数の一覧

WordPressの翻訳関数をソースコードから抜き出して一覧表にしてみました。

関数名 引数 内容
__( ) $text, $domain $textの翻訳を取得します。
esc_attr__( ) $text, $domain $textの翻訳を取得して、属性として安全に使用できるようにエスケープします。
esc_html__( ) $text, $domain $textの翻訳を取得して、HTML内で安全に使用できるようにエスケープします。
_e( ) $text, $domain $textの翻訳をecho出力します。
esc_attr_e( ) $text, $domain $textの翻訳を属性として安全に使用できるようにエスケープして、echo出力します。
esc_html_e( ) $text, $domain $textの翻訳をHTML内で安全に使用できるようにエスケープして、echo出力します。
_x( ) $text, $context, $domain $contextをコンテキスト識別子として$textの翻訳を取得します。
_ex( ) $text, $context, $domain $contextをコンテキスト識別子として$textの翻訳を取得して、echo出力します。
esc_attr_x( ) $text, $context, $domain $contextをコンテキスト識別子として$textの翻訳を取得して、属性として安全に使用できるようにエスケープします。
esc_html_x( ) $text, $context, $domain $contextをコンテキスト識別子として$textの翻訳を取得して、HTML内で安全に使用できるようにエスケープします。
_n( ) $single, $plural, $number, $domain $singleをキーとして数値$numberに対応した複数形翻訳を取得します。
_nx( ) $single, $plural, $number, $context, $domain $contextをコンテキスト識別子として、$singleをキーとして数値$numberに対応した複数形翻訳を取得します。
_n_noop( ) $singular, $plural, $domain .potファイル生成対象に加えるためのダミー関数
_nx_noop( ) $singular, $plural, $context, $domain .potファイル生成対象に加えるためのダミー関数

Poeditなどでソースコードからキーワードを抽出するとき、これらの関数を指定します。
翻訳データを作成するときは、次の記事を参考にしてみてください。

Poeditの使い方。新規から作成してmoをテーマやプラグインに適用する方法

共通情報

各関数に共通する情報を挙げておきます。

テキストドメイン

各関数の引数$domainは、テキストドメインと呼ばれています。

テキストドメインは、翻訳データを読み込む関数（load_theme_textdomain()関数またはload_plugin_textdomain()関数）の引数として与えた文字列です。

$domainは省略可能です。
省略すると 'default' が指定されたとみなされ、WordPress本体が読み込んだ翻訳データが使用されます。

属性のエスケープ

属性として安全に使用できるようにエスケープするとき、文字列内に次表の文字があるか検索し、文字があれば対応するHTMLエンティティに置き換えられます。

対象文字 変換後
& &
< &lt;
> &gt;
" &quot;
' &apos;

エスケープされた文字列は、attribute_escapeフィルターに渡されます。
このフィルターはデフォルトでは何も処理しません。

HTMLのエスケープ

HTML内で安全に使用できるようにエスケープするとき、属性のエスケープと同じ置き換えが行われます。
ただし変換結果のカスタマイズは、esc_htmlフィルターでおこなう点が異なります。

コンテキスト識別子

翻訳データには、通常は翻訳するテキストキーワードと翻訳後の文字列が一対一で登録されています。

しかし一つのテキストキーワードに複数のコンテキスト識別子を組み合わせ、複数の翻訳を登録することができます。

■例

テキストキーワード: 'hello'
┣ コンテキスト識別子: 'morning' → 翻訳: 'おはよう'
┣ コンテキスト識別子: 'afternoon' → 翻訳: 'こんにちは'
┗ コンテキスト識別子: 'night' → 翻訳: 'こんばんは'

複数形式

英語などの言語には単数形と複数形という形式があります。
WordPressで扱う翻訳データには、単数形と複数形を取り扱う目的で、一つのキーワードに対して複数の翻訳結果を含めることができます。

__( )関数

__( )関数は、キーワードに対応する翻訳を、翻訳データから取得して返します。

構文
__( $text, $domain = 'default' )

$text: 翻訳するテキストキーワード
$domain: テキストドメイン

翻訳データ内にキーワード$textが存在しない、またはテキストドメインに対応する翻訳データが読み込まれていないときは$textが返ります。

esc_attr__( )関数

esc_attr__( )関数は、キーワードに対応する翻訳を翻訳データから取得したあと、属性として安全に使用できるようにエスケープして返します。

構文
esc_attr__( $text, $domain = 'default' )

$text: 翻訳するテキストキーワード
$domain: テキストドメイン

翻訳データ内にキーワード$textが存在しない、またはテキストドメインに対応する翻訳データが読み込まれていないときは$textが翻訳結果となります。
翻訳結果は属性のエスケープ後に、関数の実行結果として返されます。

esc_html__( )関数

esc_html__( )関数は、キーワードに対応する翻訳を翻訳データから取得したあと、HTML内で安全に使用できるようにエスケープして返します。

構文
esc_html__( $text, $domain = 'default' )

$text: 翻訳するテキストキーワード
$domain: テキストドメイン

翻訳データ内にキーワード$textが存在しない、またはテキストドメインに対応する翻訳データが読み込まれていないときは$textが翻訳結果となります。
翻訳結果はHTMLのエスケープ後に、関数の実行結果として返されます。

_e( )関数

_e( )関数は、キーワードに対応する翻訳を翻訳データから取得してecho出力します。

構文
_e( $text, $domain = 'default' )

$text: 翻訳するテキストキーワード
$domain: テキストドメイン

この関数は__( )関数と同じ処理を行った後、echo出力します。

esc_attr_e( )関数

esc_attr_e( )関数は、キーワードに対応する翻訳を翻訳データから取得したあと、属性として安全に使用できるようにエスケープしてecho出力します。

構文
esc_attr_e( $text, $domain = 'default' )

$text: 翻訳するテキストキーワード
$domain: テキストドメイン

この関数はesc_attr__( )関数と同じ処理を行った後、echo出力します。

esc_html_e( )関数

esc_attr_e( )関数は、キーワードに対応する翻訳を翻訳データから取得したあと、HTML内で安全に使用できるようにエスケープしてecho出力します。

構文
esc_html_e( $text, $domain = 'default' )

$text: 翻訳するテキストキーワード
$domain: テキストドメイン

この関数はesc_html__( )関数と同じ処理を行った後、echo出力します。

_x( )関数

_x( )関数は、キーワードとコンテキスト識別子に対応する翻訳を、翻訳データから取得して返します。

構文
_x( $text, $context, $domain = 'default' )

$text: 翻訳するテキストキーワード
$context: コンテキスト識別子
$domain: テキストドメイン

翻訳データ内にキーワード$textとコンテキスト識別子$contextの組み合わせが存在しない、またはテキストドメインに対応する翻訳データが読み込まれていないときは$textが返ります。

_ex( )関数

_ex( )関数は、キーワードとコンテキスト識別子に対応する翻訳を、翻訳データから取得してecho出力します。

構文
_ex( $text, $context, $domain = 'default' )

$text: 翻訳するテキストキーワード
$context: コンテキスト識別子
$domain: テキストドメイン

この関数は_x( )関数の実行結果をecho出力します。

esc_attr_x( )関数

esc_attr_x( )関数は、キーワードとコンテキスト識別子に対応する翻訳を翻訳データから取得したあと、属性として安全に使用できるようにエスケープして返します。

構文
esc_attr_x( $text, $context, $domain = 'default' )

$text: 翻訳するテキストキーワード
$context: コンテキスト識別子
$domain: テキストドメイン

翻訳データ内にキーワード$textとコンテキスト識別子$contextの組み合わせが存在しない、またはテキストドメインに対応する翻訳データが読み込まれていないときは$textが翻訳結果となります。
翻訳結果は属性のエスケープ後に、関数の実行結果として返されます。

※この関数のecho出力版はありません。

esc_html_x( )関数

esc_html_x( )関数は、キーワードとコンテキスト識別子に対応する翻訳を翻訳データから取得したあと、HTML内で安全に使用できるようにエスケープして返します。

構文
esc_html_x( $text, $context, $domain = 'default' )

$text: 翻訳するテキストキーワード
$context: コンテキスト識別子
$domain: テキストドメイン

翻訳データ内にキーワード$textとコンテキスト識別子$contextの組み合わせが存在しない、またはテキストドメインに対応する翻訳データが読み込まれていないときは$textが翻訳結果となります。
翻訳結果はHTMLのエスケープ後に、関数の実行結果として返されます。

※この関数のecho出力版はありません。

_n( )関数

_n( )関数は、引数で与えられたキーワードと数値から、単数形または複数形の翻訳結果を返します。

構文
_n( $single, $plural, $number, $domain = 'default' )

$single: 翻訳するテキストキーワード
$plural: 複数形の翻訳結果
$number: 単数か複数かの判断値
$domain: テキストドメイン

キーワード$singleを使用して翻訳データから翻訳結果が取得されます。
翻訳結果が複数形式の場合、数値$numberを参照して適切なものが返されます。
複数形式でない場合は、数値が1なら翻訳結果が、1でないなら$pluralが返ります。

翻訳データ内にキーワード$textが存在しない、またはテキストドメインに対応する翻訳データが読み込まれていないとき、$numberが1なら$singleが、1以外なら$pluralが翻訳結果となります。

※この関数のecho出力版はありません。

_nx( )関数

_nx( )関数は、引数で与えられたキーワードとコンテキスト識別子および数値から、単数形または複数形の翻訳結果を返します。

構文
_nx( $single, $plural, $number, $context, $domain = 'default' )

$single: 翻訳するテキストキーワード
$plural: 複数形の翻訳結果
$number: 単数か複数かの判断値
$context: コンテキスト識別子
$domain: テキストドメイン

この関数は検索条件としてコンテキスト識別子が追加されているほかは、_n( )関数と同じです。

※この関数のecho出力版はありません。

_n_noop( )関数

_n_noop( )関数は、連想配列を生成して返します。

構文
_n_noop( $singular, $plural, $domain = null )

$single: 翻訳するテキストキーワード
$plural: 複数形の翻訳結果
$domain: テキストドメイン

次の連想配列を返します。

  • array(
  • 0 => $singular,
  • 1 => $plural,
  • 'singular' => $singular,
  • 'plural' => $plural,
  • 'context' => null,
  • 'domain' => $domain,
  • );
AFFS Simple Code Viewer
Copy

主な目的としては、ソースファイルからの.poファイル生成時に、将来的に使用するキーワードを含めることです。

_nx_noop( )関数

_nx_noop( )関数は、連想配列を生成して返します。

構文
_nx_noop( $singular, $plural, $context, $domain = null )

$single: 翻訳するテキストキーワード
$plural: 複数形の翻訳結果
$context: コンテキスト識別子
$domain: テキストドメイン

次の連想配列を返します。

  • array(
  • 0 => $singular,
  • 1 => $plural,
  • 'singular' => $singular,
  • 'plural' => $plural,
  • 'context' => $context,
  • 'domain' => $domain,
  • );
AFFS Simple Code Viewer
Copy

主な目的としては、ソースファイルからの.poファイル生成時に、将来的に使用するキーワードを含めることです。