WPGraphQLを使用した多言語コンテンツのクエリ方法 – 言語のフィルタリングと翻訳

ヘッドレスWordPressサイトでWPGraphQLを使用して、言語固有のコンテンツをクエリし、翻訳を取得し、多言語メニューを公開する方法を説明します。WPML GraphQLは、WPGraphQLスキーマに言語引数と翻訳フィールドを追加するため、Next.js、Nuxt、Astro、Gatsbyなどのフロントエンドは、1回のラウンドトリップで適切な言語のコンテンツを取得できます。

始める前に

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

WPGraphQL（WPGraphQLプロジェクトのオープンソースプラグイン）
WPMLおよびWPML 文字列翻訳
WPML GraphQL（このページで解説するアドオン）

Advanced Custom Fieldsも使用する場合：

Advanced Custom Fields Multilingual (ACFML)
WPGraphQL for Advanced Custom Fields（WPGraphQLプロジェクト提供）

以下のクエリで結果を返すには、事前にWPMLで翻訳元コンテンツを翻訳しておく必要があります。すべてを自動翻訳する（WPML 5のデフォルト）を有効にしている場合、コンテンツの公開時にバックグラウンドで翻訳が生成されます。手動セットアップの場合は、WPML翻訳ダッシュボードからコンテンツを翻訳に送信します。以下のGraphQLクエリは、これらの翻訳された投稿やタームをフィルタリングして返します。

GraphQL IDE – クエリのテスト場所

WPGraphQLは、WordPress管理画面にGraphQLGraphQL IDE画面を追加します。IDEのQuery Composerには、WPMLのlanguage引数やtranslationsフィールドを含む利用可能なすべてのフィールドがリストされ、ライブサイトに対してクエリを実行できます。フロントエンドフレームワークに組み込む前に、ここでクエリをテストしてください。

各言語のGraphQLエンドポイント

WPGraphQLは/graphqlで応答します。language引数のないクエリは、デフォルト言語のコンテンツを返します。別の言語のコンテンツを取得するには、クエリにwhere: { language: "es" }を追加します。

言語ごとのコンテンツのクエリ

投稿、カスタム投稿タイプ、タクソノミーターム、メニュー、メニュー項目、コメントなどのリストクエリにwhere: { language: "<code>" }を追加します。言語コードは、WPMLが各所で使用しているコード（en、es、fr、pt-ptなど）と同じです。すべての言語のコンテンツを一度に返すには、language: "all"を渡します。

query PostsES {
  posts(where: { language: "es" }) {
    nodes {
      slug
      uri
      categories {
        nodes { name }
      }
    }
  }
}

トップレベルのノードが言語でフィルタリングされると、関連する項目（カテゴリー、タグ、カスタムタクソノミー）も自動的に同じ言語になります。上記のクエリは、追加の引数を必要とせずに、スペイン語のカテゴリーを持つスペイン語の投稿を返します。

1回のクエリでノードのすべての翻訳を取得

投稿またはタクソノミークエリにtranslationsフィールドを追加すると、同じペイロードでそのノードの他言語バージョンが返されます。

query PostsWithTranslations {
  posts(where: { language: "en" }) {
    nodes {
      slug
      uri
      language { code }
      translations {
        slug
        uri
        language { code }
      }
    }
  }
}

各投稿は、英語のフィールドに加えて、他言語のスラッグとURIの配列とともに返されます。これは、ページコンテンツの横にレンダリングされる言語スイッチャーが使用する形式です。1回のリクエストで、訪問者が切り替え可能なすべての選択肢を取得できます。

任意の言語のIDまたはスラッグによる特定の投稿のクエリ

単一の翻訳済み投稿を（翻訳されたスラッグまたはデータベースIDによって）直接取得するには、単数形のpostクエリにidTypeを使用します。

query PostBySlug {
  post(id: "hola-mundo", idType: SLUG) {
    title
    slug
    uri
    language { code }
  }
}

query PostById {
  post(id: "2", idType: DATABASE_ID) {
    title
    slug
    uri
    language { code }
  }
}

どちらのクエリも、フロントエンドでさらにフィルタリングすることなく、翻訳された投稿（タイトル、スラッグ、URI）を返します。

多言語メニュー

同じwhere: { language }引数を使用して、言語ごとにメニューとメニュー項目をクエリします。テーマのメニュー位置の項目を取得するには、位置も追加します。

query NavES {
  menuItems(where: { language: "es", location: PRIMARY }) {
    nodes {
      label
      url
      path
    }
  }
}

特定の言語のメニューをリストするには、menusクエリを使用します。

query MenusES {
  menus(where: { language: "es" }) {
    nodes {
      name
      locations
    }
  }
}

各メニュー項目のlabelおよびurlは、クエリされた言語で返されます。翻訳された投稿にリンクするメニュー項目は、自動的に翻訳されたURIに解決されます。単数形のmenuクエリにはlanguage引数がないため、言語の選択にはmenusまたはmenuItemsを使用します。

インストール済み言語 – 言語スイッチャー用

グローバルな言語スイッチャー（単一の投稿に依存しないもの）の場合、languagesおよびdefaultLanguageクエリを使用して、サイト上のすべての言語をリストします。

query SiteLanguages {
  languages {
    code
    country_flag_url
    default_locale
    native_name
    translated_name
    url
  }
  defaultLanguage {
    code
    native_name
  }
}

有効な言語ごとに、国旗のURL、ネイティブ名、翻訳名、およびその言語のホームURLを含む1つのノードを返します。これは、言語リストをハードコーディングせずに、国旗とラベルのスイッチャーをレンダリングするのに十分なデータです。

言語ごとのACFカスタムフィールドのクエリ

ACFMLとWPGraphQL for ACFが有効な場合、投稿またはカスタム投稿タイプのACFフィールドは、その投稿に保存されている値を返します。各翻訳には独自の値があるため、必要な言語で投稿をクエリします。追加の引数は必要ありません。

単一の投稿に紐付かないACF Options Pagesの場合は、Options Pageクエリにlanguage引数を追加します。

query Settings {
  myOptionPage(language: "de") {
    addressFieldGroup {
      addressTitle
      repeaterAddressDetails { addressDetails }
    }
  }
}

この引数には、サイトの有効な言語のいずれかに一致する言語コードを指定します。

WPGraphQL for ACF 3.0.0以降、オプションページは、そのページでshow_in_graphqlを有効にした場合にのみGraphQLスキーマに含まれます。これがないと、オプションページクエリとそのlanguage引数は存在しません。コードでオプションページを登録する場合は、そこに設定を追加します。

acf_add_options_page( array(
  'page_title'         => 'Site Settings',
  'menu_slug'          => 'site-settings',
  'show_in_graphql'    => true,
  'graphql_field_name' => 'siteSettings',
) );

翻訳された投稿者情報

WPML GraphQLは、ユーザーの翻訳されたfirstName、lastName、nickname、およびdescriptionを返します。これらを翻訳するには、以下の手順に従います。

WPML文字列翻訳ページに移動します。
Translate User propertiesオプションで、ユーザーロールを選択して保存します。
Authorsドメインの文字列を翻訳します。

既知の問題と回避策

一部のクエリ形式における翻訳されたURI。URI（contentNode(id: "/de/some-slug/", idType: URI)）で翻訳された投稿を取得する際、返されたURIがその言語で公開されているものと一致するか確認してください。一部のクエリ形式では、一貫性のないパスが返されることがあります。ルーティングに組み込む前に、GraphQL IDEでテストしてください。
language引数のないACF Options Pagesは、デフォルト言語にフォールバックします。多言語サイトのOptions Pageクエリでは、常にlanguageを渡してください。

ここに記載されていない統合の問題が発生した場合は、WPMLサポートチームがWPGraphQLスタックのWPML側について24時間年中無休で対応します。

執筆者：Amir最終更新日：2026年7月2日