Как запрашивать многоязычный контент с помощью 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, и он выполняет запросы к Вашему рабочему сайту. Протестируйте запросы там, прежде чем внедрять их в свой фронтенд-фреймворк.

Запрос контента по языку

Добавьте 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) без дополнительной фильтрации на фронтенде.

Многоязычные меню

Запрашивайте меню и пункты меню по языку с помощью того же аргумента language:

query NavES {
  menu(language: "es", id: "primary", idType: SLUG) {
    menuItems {
      nodes {
        label
        url
        path
      }
    }
  }
}

label и url каждого пункта меню возвращаются на запрашиваемом языке. Пункты меню, ссылающиеся на переведенные записи, автоматически разрешаются в переведенный URI. Эта поддержка была добавлена в WPML GraphQL 1.1.0.

Установленные языки — для переключателя языков

Для глобального переключателя языков (независимого от какой-либо отдельной записи) используйте запросы 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, которые не привязаны к одной записи, добавьте аргумент language к запросу страницы параметров:

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

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

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

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

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