WordPressでのACFカスタムフィールドの翻訳 – フィールドグループ、リピーター、オプションページ

開始する前に

以下のプラグインをインストールして有効化します。

• Advanced Custom FieldsまたはACF Pro
• WPMLおよびWPML 文字列翻訳
• ACFML（このページで解説するアドオン）

フィールドグループは、すでにACFで設定されている必要があります。フィールドごとの翻訳設定は後から変更できるため、作業の順序は問題になりません。フィールドグループを設定してから、ACFMLの作業に戻ります。

各フィールドグループの翻訳オプションの選択

翻訳時、すべてのACFフィールドグループが同じように動作するわけではありません。ACFMLでは、各フィールドグループに対して3つの翻訳オプションを提供しています。オプションを選択するには、以下の手順を実行します。

1. ACF → フィールドグループに移動し、フィールドグループを編集します。
2. 「Multilingual Setup」セクションの「Select a translation option for this field group」で、希望するオプションの「Choose」をクリックします。
3. フィールドグループを保存します。

ACFMLは、サイトに推奨されるオプションを「recommended for this site」としてマークします。後で別のオプションを選択するには、「Change option」をクリックします。古いバージョンのACFMLでは、最初の2つのオプションを「Same fields across languages」および「Different fields across languages」と呼んでいます。

すべての言語で同じコンテンツ（翻訳済み）

ほとんどのACFサイトにおける一般的な設定です。すべての言語の訪問者が、それぞれの言語で同じページを閲覧します。テキストは翻訳されますが、レイアウトと設定は同じままです。通常、「Our Team（チーム紹介）」ページがこの例に該当します。チーム構成はすべての言語で同じであるため、各メンバーの名前とプロフィールは翻訳され、フィールド構造はそのまま維持されます。デフォルト言語でチームを入力し、WPML → 翻訳 → ダッシュボードから投稿を翻訳に送信します。翻訳された値は同じフィールドに戻されます。このオプションは、自動翻訳および「すべてを翻訳する」で機能します。

各言語で独自のコンテンツを使用

各言語で同じフィールドグループに異なるコンテンツを表示する場合に、このオプションを使用します。一般的な例は、地域ごとのイベントを開催する企業です。英語の「Events（イベント）」ページには英語圏向けのイベントが表示され、フランス語のページにはフランス語圏向けのイベントが表示されます。フィールドは元の言語のコピーとして開始されます。その後、各言語は独自の値を保持します。各言語の編集はWordPressエディタで行います。投稿を開き、「言語」ボックス内の翻訳先言語のプラスアイコンをクリックして、その言語の値を入力し、公開します。その後WPMLは言語バージョンを同期せず、自動翻訳も適用されません。

エキスパート

一部のフィールドは翻訳し、一部は同じままにし、一部は一度だけコピーした後に各言語で変更するなど、混在させる必要がある場合にこのオプションを使用します。「エキスパート」を選択し、各フィールドの翻訳設定を手動で設定します。「Events」の例では、タイトルと説明には「翻訳」を使用し、価格、日付、住所には「コピー」を使用します。ACFMLは、新しいフィールドグループにこのオプションを推奨していません。PHPまたはローカルJSONで定義されたフィールドグループには、翻訳オプションがない場合があります。その場合、サイトをWPML 5.2に更新する前からフィールドグループが存在する場合にのみ「エキスパート」が使用されます。

各ACFフィールドタイプの翻訳設定

値を保存するすべてのフィールドには、4つの翻訳設定のいずれかがあります。

• 翻訳：訪問者はそれぞれの言語で値を閲覧します。WPMLが翻訳を入力します。編集は翻訳エディタで行います。
• コピー：すべての言語の訪問者が、元の言語とまったく同じ内容を閲覧します。フィールドは他の言語ではロックされます。
• 一度だけコピー：値は元の言語のコピーとして開始されます。その後、各言語で手動で編集します。翻訳でフィールドを空にした場合、空のままになります。WPMLが元の値を再度コピーすることはありません。
• 翻訳しない：翻訳はこの値なしで開始されます。各言語で手動で入力できます。

「すべての言語で同じコンテンツ（翻訳済み）」または「各言語で独自のコンテンツを使用」を選択すると、ACFMLは各フィールドにそのフィールドタイプに推奨される設定を適用します。以下の表は、これらの推奨設定を示しています。1つのフィールドに異なる設定を適用するには、「エキスパート」を使用します。サイト全体でフィールドタイプの推奨設定を変更するには、acfml_field_group_mode_field_translation_preferenceフィルターを使用します（下記の「Developer Hooks for Edge Cases」を参照）。

タブ、アコーディオン、メッセージ、およびセパレータフィールドは値を保存しないため、翻訳設定はありません。他のプラグインのフィールドタイプなど、表にないフィールドタイプには、両方の翻訳オプションで「コピー」が適用されます。

リピーター、フレキシブルコンテンツ、グループ、およびクローンフィールド

これらのフィールドは他のフィールドを保持します。コンテナフィールドの推奨設定は「コピー」または「一度だけコピー」です。ACFMLは、コンテナフィールド自体には「翻訳」を提供していません。各サブフィールドには独自の翻訳設定があります。

「すべての言語で同じコンテンツ（翻訳済み）」を使用すると、リピーターおよびフレキシブルコンテンツフィールドの行はデフォルト言語と同じ順序に保たれます。「エキスパート」を使用する場合、または投稿で異なるオプションのフィールドグループを使用する場合、投稿エディタに「ACFML Synchronise translations」ボックスが表示されます。これは、投稿に翻訳があり、リピーターまたはフレキシブルコンテンツフィールドが含まれている場合に、元の投稿に表示されます。すべての言語で行を揃えておくには、「Keep repeater and flexible sub-fields in the same order as the default language」を選択します。

基本フィールド

コンテンツフィールド

選択肢フィールド

jQueryフィールド

レイアウトフィールド

関連フィールド

リンクフィールドの場合、翻訳にはリンクテキストとURLが含まれます。URLがサイト内のページを指しており、それを変更しない場合、WPMLは訪問者の言語でそのページを表示します。

URLおよびリンクフィールド

ACFML 5.0以降、URLおよびリンクフィールドはデフォルトで翻訳設定を使用します。

双方向の関連

ACF 6.2以降、関連、投稿オブジェクト、タクソノミー、ユーザーの各フィールドは双方向に設定できます。フィールドでターゲットを選択すると、ACFはターゲットのペアとなるフィールドに投稿を追加します。たとえば、書籍DuneのAuthorフィールドをFrank Herbertに設定すると、ACFはFrank HerbertのBooksフィールドにDuneを追加します。

ACFMLは各言語でペアを維持します。

• WPMLがフィールドを翻訳にコピーすると、ACFMLはそのフィールドを同じ言語のターゲットに指定します。その後、ACFMLはそのターゲットのペアとなるフィールドに翻訳を追加します。スペイン語のDuneにはスペイン語のFrank Herbertが表示され、スペイン語のFrank Herbertにはスペイン語のDuneがリストされます。
• フィールドでコピーを使用しており、元の投稿のターゲットを変更すると、WPMLは翻訳を更新します。ACFMLは、その言語の新しいターゲットに翻訳を追加し、古いターゲットから削除します。
• ACFMLは翻訳言語のターゲットのみを変更します。元の言語の投稿は独自のペアを維持します。
• ターゲットにまだ翻訳がない場合、翻訳は元のターゲットを指し、ACFMLは元のターゲットを変更しません。後でターゲットを翻訳すると、ACFMLはフィールドを新しい翻訳に指定し、ペアとなるフィールドに投稿を追加します。フィールドにはターゲットが1回リストされます。
• ユーザーには翻訳がないため、ACFMLはユーザーのペアとなるフィールドに翻訳を追加しません。そのフィールドは元の投稿を維持します。フィールドでコピーを使用していない限り、ACFMLは別の言語でその投稿の翻訳を表示します。

これは、これらのフィールドタイプで推奨される設定であるコピーおよび一度だけコピーの設定で機能します。また、WPMLで投稿を複製する場合にも機能します。

ACFブロックの翻訳

デフォルトでは、ACFブロックはフィールドの値をカスタムフィールドとしてではなく、投稿コンテンツ内のブロックの内部に保存します。ACFMLは、これらの値を投稿の他の部分と一緒に、同じ翻訳ジョブで翻訳に送信します。

• ブロックは、このブロックを配置ルールとするフィールドグループの翻訳オプションとフィールド設定を使用します。
• ACFMLは、翻訳を使用するフィールドのみを送信します。コピー、一度だけコピー、または翻訳不可を使用するフィールドは、元のブロックの値を維持します。
• ブロック内の繰り返しフィールドや柔軟なコンテンツフィールドも、ネストされている場合を含めて翻訳されます。各サブフィールドは独自の翻訳設定を使用します。
• block.jsonのacfセクションに"usePostMeta": trueがあるブロックは、その値をブロック内ではなく、投稿のカスタムフィールドとして保存します。これらの値は、フィールドグループの翻訳オプションとフィールド設定を使用して、投稿の他のカスタムフィールドと同様に翻訳されます。
• ブロックで使用するフィールドグループの翻訳設定を変更すると、WPMLは既存の翻訳を更新するかどうかを尋ねます。確定すると、WPMLはこれらの投稿の翻訳に更新が必要であるというマークを付けます。変更を適用するには、それらを再度翻訳に送信してください。翻訳不可への変更ではマークされません。

block.jsonで宣言されたフィールド

ACF 6.8.1以降、ブロックはblock.jsonファイルのacf.fieldsでフィールドを宣言できます。ACFはこれらのフィールドのフィールドグループを作成しますが、管理画面でこのフィールドグループを編集することはできません。ACFMLは、PHPで登録されたフィールドグループと同様に、すべての言語で同じコンテンツ、翻訳済みオプションと、各フィールドタイプに推奨される設定を付与します。

グループ全体で別のオプションを使用するには、block.jsonのacfセクション、またはacf_register_block_type()にacfml_field_group_modeを追加します。使用可能な値は、translation（すべての言語で同じコンテンツ、翻訳済み）、localization（各言語に独自のコンテンツ）、およびadvanced（エキスパート）です。ACFMLはこれ以外の値を無視します。

{
    "name": "acme/event-card",
    "title": "Event Card",
    "acf": {
        "mode": "preview",
        "acfml_field_group_mode": "localization",
        "fields": [ ... ]
    }
}

1つのフィールドの設定を行うには、そのフィールドにwpml_cf_preferencesを追加します。ACFMLは、すべてのオプションでこの設定を維持します。エキスパートの場合、wpml_cf_preferencesを宣言したフィールドのみが設定を取得します。

block.jsonがオプションを指定していない場合、ACFMLはグループを初めて認識したときに付与したオプションを保存し、その後もそれを維持します。古いバージョンのACFMLでこれらのブロックを使用していたサイトでは、保存されるオプションはエキスパートになります。

PHPまたはJSONで登録されたフィールドの環境設定

PHP（acf_add_local_field_group()を使用）またはACFのローカルJSON機能を通じて登録されたACFフィールドグループは、管理画面で管理されないため、管理画面から翻訳の環境設定を取得しません。フィールドを登録するのと同じ場所で環境設定を行ってください。

フィールドグループの翻訳オプションを設定するには、定義にacfml_field_group_modeキーを追加し、translation、localization、またはadvanced（エキスパート）を指定します。定義に翻訳オプションが設定されていない場合、ACFMLはそのグループを初めて検出した際に、フィールドグループに「すべての言語で同じコンテンツ（翻訳）」オプションを付与します。ACFMLはこのオプションを保存し、その後も保持します。サイトをWPML 5.2にアップデートする前から存在するフィールドグループは、エキスパートを維持します。

フィールドグループ定義の各フィールドに、wpml_cf_preferencesキーを追加します。値は4つの翻訳環境設定にマッピングされる整数です。0は翻訳不可（WPMLはフィールドを無視します）、1はコピー（値は言語間で同期されます）、2は翻訳（値は翻訳されます）、3は一度だけコピー（値は新しい翻訳にコピーされ、その後各言語で個別に編集できます）を表します。

最小限の例：

acf_add_local_field_group( [
    'key'    => 'group_1',
    'title'  => 'My Group',
    'fields' => [
        [
            'key'                 => 'field_1',
            'label'               => 'Sub Title',
            'name'                => 'sub_title',
            'type'                => 'text',
            'wpml_cf_preferences' => 2, // Translate.
        ],
    ],
    // ...rest of the field-group config
] );

コードでフィールドを定義した後、管理画面で認識されるように環境設定をWPMLに同期します。

1. ACF → ツールに移動します。
2. 「Translate ACF Local JSON and PHP-Registered Fields」までスクロールします。
3. 「Sync Translation Preferences for Local Fields」で「Sync once now」を選択し、「適用」をクリックします。

WPMLはフィールド定義から環境設定を読み取り、保存します。「Sync once now」は1回だけ実行されます。定義を頻繁に変更する場合は、代わりに「Sync on every request (may affect performance)」を選択してください。このオプションは、管理画面へのリクエストごとに同期を実行します。

ACFのローカルJSON機能を使用してサイト間でフィールドグループを共有する場合、ACFMLは自動的に翻訳の環境設定をJSONファイルに書き込みます。あるサイトからJSONファイルをエクスポートし、別のサイトにインポートすると、両方のサイトでACFMLが有効になっていれば、インポート先のサイトで環境設定が読み込まれます。

ACFがwp acf json import WP-CLIコマンドを使用して作成したフィールドグループ、またはAIツール向けのAbilities APIを通じて作成したフィールドグループは、データベースに保存されます。ACFMLはこれらに「すべての言語で同じコンテンツ（翻訳）」オプションと、各フィールドタイプに推奨される環境設定を付与します。インポートされたJSONにすでにacfml_field_group_modeキーが含まれている場合、ACFMLは代わりにそのオプションを使用します。

ローカルJSONファイルのフィールドグループ

ACFは各リクエストの非常に早い段階でacf-jsonフォルダーのフィールドグループを読み込みます。WPML 5.2以降、ACFMLも同時にこれらのフィールドグループを読み込みます。そのため、翻訳の環境設定を同期すると、JSONフィールドグループも同期の対象になります。その後、WPMLはJSONファイル内の環境設定を使用します。

JSONファイルでは、PHPの場合と同じ値を使用して、各フィールドにwpml_cf_preferencesを追加します。このキーは、フィールドグループの翻訳オプションに関係なく、各フィールドの環境設定を設定します。この例ではエキスパートを使用しています。

{
    "key": "group_event",
    "title": "Event",
    "acfml_field_group_mode": "advanced",
    "fields": [
        {
            "key": "field_event_title",
            "label": "Event Title",
            "name": "event_title",
            "type": "text",
            "wpml_cf_preferences": 2
        },
        {
            "key": "field_event_price",
            "label": "Price",
            "name": "event_price",
            "type": "number",
            "wpml_cf_preferences": 1
        }
    ]
}

JSONフィールドグループの環境設定とラベルをWPMLに送信するには、以下の手順を実行します。

1. ACF → ツールに移動します。
2. 「Translate ACF Local JSON and PHP-Registered Fields」までスクロールします。
3. 「Sync Translation Preferences for Local Fields」で「Sync once now」または「Sync on every request (may affect performance)」を選択します。
4. 「Register Labels for Translation」で「Register labels now」を選択します。
5. 「適用」をクリックします。

結果を確認するには、WPML → 設定に移動し、「カスタムフィールド翻訳」でフィールドを探します。各フィールドにはJSONファイルからの環境設定が表示されます。また、ACFMLは、acf-jsonフォルダー内やPHPで登録されたなど、コード内にのみ存在するフィールドグループ、投稿タイプ、タクソノミー、オプションページのラベルも登録します。これらは他のフィールドグループのラベルと同様に翻訳します（以下のACFフィールドラベルの翻訳を参照してください）。

ACFフィールドラベルの翻訳

ACFフィールドラベルは、WordPressエディタやフロントエンドで各カスタムフィールドを識別するための名前です（例：電話番号、住所）。これらはフィールドの値とは別に翻訳され、投稿の翻訳ジョブではなく、WPML 文字列翻訳に保存されます。

フィールドラベルを翻訳に送信するには、以下の手順を実行します。

1. WPML → 翻訳 → ダッシュボードを開きます。
2. 「ACFフィールドグループ」セクションを展開します。
3. 翻訳したいフィールドグループのField Group Labels項目を選択します。
4. 翻訳方法（PTC、翻訳者、または自分で翻訳）を選択して送信します。

翻訳が完了すると、翻訳されたラベルがフロントエンドに自動的に表示されます。

フィールドラベルの翻訳の停止

デフォルトでは、投稿の翻訳ジョブにフィールドラベルは含まれません。ダッシュボードからField Group Labelsアイテムを送信した場合にのみ翻訳されます。送信しない場合、ACFは元のラベルを表示します。翻訳が存在する場合でも元のラベルを表示するには、acfml_should_translate_acf_entityフィルターを使用し、スキップするフィールドまたはフィールドグループに対してfalseを返します。ACFMLフックと定数のリファレンスに例があります。

ACFフィールドの選択肢の翻訳

選択フィールド（Select、Checkbox、Radio Button、Button Group）には、独自のオプションラベル（例：Small / Medium / Large）があります。これらも投稿の翻訳内ではなく、フィールドラベルと一緒に存在します。同じ方法で送信します。

1. WPML → 翻訳 → ダッシュボードを開きます。
2. ACF Field Groupセクションを展開します。
3. 選択値を翻訳するフィールドグループを選択します。
4. 翻訳方法を選択して送信します。

ACFオプションページの翻訳

ACFオプションページ（Contact details、Header settings、Footer linksなどのグローバル設定画面）は、投稿とは別に、独自のオブジェクトタイプとして翻訳されます。

1. WPML → 翻訳 → ダッシュボードを開きます。
2. ACF Optionsセクションを展開します。
3. 翻訳するオプションページを選択します。
4. 翻訳方法を選択して送信します。

各言語のオプションページの値は、ACFがその言語のコンテキストでオプションを読み込むと自動的に表示されます。

オプションページのフィールドグループの翻訳オプションによって、各フィールドの処理が決まります。

• 翻訳を使用するフィールドは、翻訳ダッシュボードから送信するACF Optionsアイテムに入ります。翻訳が完了すると、ACFMLはその言語のオプションページに値を書き込みます。RepeaterおよびFlexible Contentフィールドは、元の言語と同じ行を取得します。
• コピーを使用するフィールドは、すべての言語で元の値を取得します。元の言語を保存すると、ACFMLが他の言語を更新します。
• 一度だけコピーを使用するフィールドは、元の言語のコピーとして開始されます。その後、各言語のオプションページで編集します。

言語によってオプションが異なる場合は、Each language has its own contentを使用します。例えば、英語のオプションページには3人の販売代理店がリストされ、スペイン語には2人がリストされる場合などです。このオプションを選択するには、他のフィールドグループと同様にフィールドグループを編集します。

完了した翻訳を変更するには、WPML → 翻訳 → 翻訳ジョブに移動し、ACF Optionsジョブの編集をクリックします。翻訳された値はWPML → 文字列翻訳でも編集できます。そこで翻訳を保存すると、ACFMLはその言語のオプションページに書き込みます。

サイトのデフォルト言語を変更した場合、既存のオプションページの値は書き込まれた言語のまま維持されます。ACFは変更前と同じ値を読み込みます。

コード内では、get_field( 'my_field', 'option' )は現在の言語の値を返します。do_action( 'wpml_switch_language', 'fr' )の後は、フランス語の値を返します。これはカスタムのpost_idを持つオプションページでも機能します。

よくある落とし穴

• フィールドラベルが翻訳されていないように見える。これらは投稿の翻訳ではなく、文字列翻訳に存在します。ダッシュボードからフィールドグループのField Group Labelsアイテムを送信してください（上記のACFフィールドラベルの翻訳を参照）。
• 選択値が翻訳されていないように見える。仕組みは同じです。オプション値が含まれるように、ダッシュボードのACF Field Groupセクションからフィールドグループを送信してください。
• Repeaterの行が同期されない。フィールドグループがおそらくExpertを使用しています。元の投稿を編集し、ACFML Synchronise translationsボックスでKeep repeater and flexible sub-fields in the same order as the default languageを選択して、投稿を更新します。または、フィールドグループをSame content in every language, translatedに切り替えます。
• 条件付きロジックが予期しない動作をする。制御フィールドがコピーまたは翻訳しないに設定されている場合、条件付きの動作はすべての翻訳で翻訳元言語の値に従います。言語ごとに値が異なる必要がある場合は、制御フィールドを翻訳に設定してください。
• ローカルフィールド（PHPで登録）が管理画面で設定された翻訳設定を無視する。フィールドグループの定義自体にwpml_cf_preferencesキーを設定し、ACF → ツールから同期します。手順は上記のPHPまたはJSONで登録されたフィールドの設定にあります。

エッジケース向けのデベロッパーフック

プログラムによる制御（特定のフィールドを翻訳から除外する、サイト全体でフィールドタイプのデフォルト設定を上書きする、翻訳者から注釈を隠す、または投稿の翻訳ジョブからフィールドグループの文字列を除外するなど）のために、ACFMLには2つのフィルターと4つの定数があります。コード例を含む完全なリファレンスは、ACFMLフックと定数のリファレンスにあります。