Как запрашивать многоязычный контент с помощью WPGraphQL — фильтрация по языку и переводы

Перед началом работы

Установите и активируйте следующие плагины:

• 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 добавляет экран GraphQL → GraphQL IDE в админ-панель WordPress. В Query Composer среды IDE перечислены все доступные поля, включая аргумент 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 }
      }
    }
  }
}

Когда узел верхнего уровня фильтруется по языку, связанные элементы (рубрики, метки, произвольные таксономии) автоматически получают тот же язык. Приведенный выше запрос возвращает записи на испанском языке с рубриками на испанском языке, дополнительные аргументы не требуются.

Получение всех переводов узла в одном запросе

Добавьте поле translations в любой запрос записи или таксономии, чтобы вернуть версии узла на других языках в том же ответе:

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

Каждая запись возвращается со своими английскими полями плюс массив ее слагов и URI на других языках. Именно такую структуру использует переключатель языков, отображаемый рядом с контентом страницы: один запрос — и все альтернативы, на которые может переключиться посетитель.

Запрос конкретной записи по 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-адресом языка. Этих данных достаточно для отображения переключателя с флагами и названиями без жесткого кодирования списка языков.

Запрос произвольных полей ACF по языкам

Когда активны ACFML и WPGraphQL for ACF, поля ACF в записи или произвольном типе записи возвращают значения, сохраненные для этой записи. Каждый перевод имеет свои собственные значения, поэтому запрашивайте запись на нужном Вам языке. Дополнительные аргументы не требуются.

Для страниц параметров ACF (Options Pages), которые не привязаны к отдельной записи, добавьте аргумент language в запрос страницы параметров:

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

Аргумент ожидает код языка, который соответствует одному из активных языков Вашего сайта.

Начиная с версии WPGraphQL for ACF 3.0.0, страница параметров присутствует в схеме GraphQL только в том случае, если для нее включен параметр show_in_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 пользователей. Чтобы перевести их:

1. Перейдите на страницу WPML → Перевод строк.
2. В настройке Translate User properties выберите роли пользователей и сохраните.
3. Переведите строки в домене Authors.

Известные ограничения и обходные решения

• Переведенные URI в некоторых формах запросов. При получении переведенной записи по URI (contentNode(id: "/de/some-slug/", idType: URI)) убедитесь, что возвращаемый URI совпадает с тем, что опубликовано на этом языке — некоторые формы запросов возвращают несогласованные пути. Протестируйте в GraphQL IDE перед внедрением в маршрутизацию.
• Страницы параметров ACF без аргумента language возвращаются к языку по умолчанию. Всегда передавайте language для запросов страницы параметров на многоязычных сайтах.

Если Вы столкнулись с проблемой интеграции, не указанной здесь, команда поддержки WPML доступна 24/7 для решения вопросов на стороне WPML в стеке WPGraphQL.