基本文字列

最も一般的に使用される関数は () です。これは引数の翻訳を返します: 

  1. __( 'Blog Options', 'my-theme' );

もう一つのシンプルなものは _e() で、これは引数の翻訳を出力します。次のように書く代わりに: 

  1. echo __( 'WordPress is the best!', 'my-theme' );

短い形式を使用できます: 

  1. _e( 'WordPress is the best!', 'my-theme' );

() は JavaScript 用にも利用可能です。

変数

文字列に変数を使用している場合、以下の例のように、プレースホルダーを使用する必要があります。 

  1. echo 'Your city is $city.'

printf ファミリーの関数を使用してください。特に役立つのは printf と sprintf です。例えば: 

  1. printf(
  2.    /* translators: %s: Name of a city */
  3.    __( 'Your city is %s.', 'my-theme' ),
  4.    $city
  5. );

翻訳用の文字列はテンプレート "Your city is %s." であり、ソースと実行時の両方で同じです。

文字列にプレースホルダーが複数ある場合は、引数の入れ替えを使用することをお勧めします。この場合、シングルクォート (') は必須です: ダブルクォート (") は PHP に $s を s 変数として解釈させるため、これは望ましくありません。 

  1. printf(
  2.    /* translators: 1: Name of a city 2: ZIP code */
  3.    __( 'Your city is %1$s, and your zip code is %2$s.', 'my-theme' ),
  4.    $city,
  5.    $zipcode
  6. );

ここでは、郵便番号が都市名の後に表示されます。一部の言語では、郵便番号と都市を逆の順序で表示する方が適切です。上記の例のように %s プレフィックスを使用することで、これが可能になります。翻訳は次のように書くことができます: 

  1. printf(
  2.    /* translators: 1:ZIP code 2:Name of a city */
  3.    __( 'Your zip code is %2$s, and your city is %1$s.', 'my-theme' ),
  4.    $city,
  5.    $zipcode
  6. );

sprintf は JavaScript の翻訳にも利用可能です: 

  1. const zipCodeMessage = sprintf(
  2.    /* translators: 1:ZIP code 2:Name of a city */
  3.    __( 'Your zip code is %2$s, and your city is %1$s.', 'my-theme'),
  4.    city,
  5.    zipcode
  6. );

次の例は、何をしてはいけないかを示しています。

これは不正です。 

  1. // This is incorrect do not use.
  2. _e( "Your city is $city.", 'my-theme' );

翻訳用の文字列は、関連する PHP を実行せずにソースから抽出されます。例えば: 変数 $city はバンクーバーである可能性があるため、テンプレートが実行されると "Your city is Vancouver" になりますが、gettext は事前に PHP 変数の中身を知ることはできません。

文字列が翻訳されるとき、変数の値は不明であるため、翻訳者は変数 $country のすべてのケースを知っている必要があります。これは理想的ではなく、動的コンテンツを削除し、翻訳者が静的コンテンツに集中できるようにするのが最善です。

複数形

基本的な複数形の処理

アイテムの数が変わると文字列が変わる場合があります。英語では "One comment" と "Two comments" があります。他の言語では、複数の複数形が存在することがあります。WordPress でこれを処理するには、_n() 関数を使用できます。 

  1. printf(
  2.    _n(
  3.    '%s comment',
  4.    '%s comments',
  5.    get_comments_number(),
  6.    'my-theme'
  7.    ),
  8.    number_format_i18n( get_comments_number() )
  9. );

_n() は 4 つの引数を受け取ります:

  • 単数形 – 文字列の単数形（注意: 一部の言語では 1 以外の数字にも使用できるため、'%s item' を 'One item' の代わりに使用する必要があります）
  • 複数形 – 文字列の複数形
  • カウント – オブジェクトの数で、単数形または複数形のどちらを返すかを決定します（2 つ以上の形がある言語もあります）
  • テキストドメイン – テーマのテキストドメイン

関数の返り値は、指定されたカウントに対応する正しい翻訳形です。

`_n() は JavaScript 用にも利用可能です。

後での複数形処理

最初に _n_noop() または _nx_noop() で複数形の文字列を設定します。 

  1. $comments_plural = _n_noop(
  2.    '%s comment.',
  3.    '%s comments.'
  4. );

コードの後の段階で、translate_nooped_plural() を使用して文字列をロードできます。 

  1. printf(
  2.    translate_nooped_plural(
  3.    $comments_plural,
  4.    get_comments_number(),
  5.    'my-theme'
  6.    ),
  7.    number_format_i18n( get_comments_number() )
  8. );

文脈による曖昧さの解消

時には、用語が複数の文脈で使用され、他の言語では別々に翻訳する必要がありますが、英語では同じ単語が各文脈で使用されます。例えば、Post という単語は、動詞 "Click here to post your comment" と名詞 "Edit this Post" の両方として使用されることがあります。このような場合は、_x() または _ex() 関数を使用する必要があります。これは () と _e() に似ていますが、追加の引数 — 文脈があります: 

  1. _x( 'Post', 'noun', 'my-theme' );
  2. _x( 'post', 'verb', 'my-theme' );

この方法を両方のケースで使用すると、元のバージョンの文字列「Comment」が得られます。しかし、翻訳者は異なる文脈でそれぞれ異なる「Comment」文字列を翻訳することになります。

WordPress のドイツ語版からの例を挙げると: Post は Beiträge です。ドイツ語の対応する動詞形は beitragen です。

() に似ていることに注意してください。_x() には echo バージョンがあります: _ex()。前の例は次のように書くことができます: 

  1. _ex( 'Post', 'noun', 'my-theme' );
  2. _ex( 'post', 'verb', 'my-theme' );

可読性とコーディングの容易さを高めると感じるものを使用してください。

_x() and _nx() は JavaScript 用にも利用可能です。

説明

ソースコードに明確なコメントを追加して、翻訳者が ( 'g:i:s a' ) のような文字列をどのように翻訳するかを知ることができます。これは translators: という単語で始まり、すべて小文字で、gettext 呼び出しの前の最後の PHP コメントでなければなりません。以下はその例です: 

  1. /* translators: draft saved date format, see http://php.net/date */
  2. $saved_date_format = __( 'g:i:s a' );

複数行の例: 

  1. /*
  2.  * translators: Replace with a city related to your locale.
  3.  * Test that it matches the expected location and has upcoming
  4.  * events before including it. If no cities related to your
  5.  * locale have events, then use a city related to your locale
  6.  * that would be recognizable to most users.
  7.  */
  8. ?>
  9. <input placeholder="<?php esc_attr_e( 'Cincinnati' ); ?>" id="location" type="text" name="location" />

改行文字

Gettext は翻訳可能な文字列内の r (ASCII コード: 13) を好まないため、これを避けて n を使用してください。

空の文字列

空の文字列は内部 Gettext 用に予約されており、空の文字列を国際化しようとしないでください。また、翻訳者は文脈を持たないため、意味がありません。

空の文字列を国際化する正当な使用例がある場合は、翻訳者を助け、Gettext システムと平和でいるために文脈を追加してください。

文字列のエスケープ

すべての文字列をエスケープすることは良いことであり、翻訳者が悪意のあるコードを実行するのを防ぎます。国際化関数と統合されたエスケープ関数がいくつかあります。 

  1. <a title="<?php esc_attr_e( 'Skip to content', 'my-theme' ); ?>" class="screen-reader-text skip-link" href="#content" >
  2.   <?php _e( 'Skip to content', 'my-theme' ); ?>
  3. </a>
  1. <label for="nav-menu">
  2.   <?php esc_html_e( 'Select Menu:', 'my-theme' ); ?>
  3. </label>

文字列を書くためのベストプラクティス

文字列を書くためのベストプラクティスは次のとおりです。

  • 適切な英語スタイルを使用する – スラングや略語を最小限に抑える。
  • 完全な文を使用する – ほとんどの言語では、語順が英語とは異なります。
  • 段落で分割する – 関連する文を統合しますが、1 つの文字列に全ページのテキストを含めないでください。
  • 翻訳可能なフレーズに先頭または末尾の空白を残さないでください。
  • 翻訳時に文字列が2倍の長さになる可能性があると仮定してください。
  • 異常なマークアップや異常な制御文字を避ける – テキストを囲むタグを含めないでください。
  • 翻訳された文字列に不必要な HTML マークアップを入れないでください。
  • 他の言語のバージョンがある場合を除き、URL を翻訳のために残さないでください。
  • 一部の言語ではプレースホルダーの位置が変わるため、文字列に変数をプレースホルダーとして追加してください。
  1. printf(
  2.    __( 'Search results for: %s', 'my-theme' ),
  3.    get_search_query()
  4. );
  • 文字列の連結の代わりにフォーマット文字列を使用する – フレーズを翻訳し、単語ではなく –
  1. printf(
  2.    __( 'Your city is %1$s, and your zip code is %2$s.', 'my-theme' ),
  3.    $city,
  4.    $zipcode
  5. );

は常に次のより良いものです: 

  1. __( 'Your city is ', 'my-theme' ) . $city . __( ', and your zip code is ', 'my-theme' ) . $zipcode;
  • 複数の類似した文字列を翻訳しないように、同じ単語や記号を使用するようにしてください（例: 次のことをしないでください）

bash __( 'Posts:', 'my-theme' ); and __( 'Posts', 'my-theme' );@