WPML

如何使用 WPGraphQL 查询多语言内容——语言筛选与翻译

了解如何在无头 WordPress 网站上通过 WPGraphQL 查询特定语言的内容、获取翻译并展示多语言菜单。WPML GraphQL 向 WPGraphQL 架构添加了语言参数和翻译字段，因此 Next.js、Nuxt、Astro、Gatsby 或任何其他前端只需一次往返请求即可提取正确语言的内容。

开始之前

安装并激活以下插件：

  • 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 }
      }
    }
  }
}

当顶级节点按语言筛选时，关联项目（类别、标签、自定义分类法）会自动遵循相同的语言。上述查询将返回西班牙语的文章以及西班牙语的类别，无需额外的参数。

在一个查询中获取节点的所有翻译

将 translations 字段添加到任何文章或分类法查询中，以便在同一有效负载中返回节点的其他语言版本：

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

每篇文章都会返回其英语字段以及包含其他语言别名和 URI 的数组。这就是在页面内容旁边渲染的语言切换器所使用的形式：只需一次请求，即可获得访问者可以切换到的每个备用选项。

按 ID 或别名查询任何语言的特定文章

要直接获取单篇已翻译的文章（通过其已翻译的别名或数据库 ID），请使用带有 idType 的单数 post 查询：

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 参数添加到 Options Page 查询中：

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。要翻译它们：

  1. 前往 WPML字符串翻译 页面。
  2. 在翻译用户属性选项中，选择用户角色并保存。
  3. 翻译 Authors 域中的字符串。

已知限制和临时解决方法

  • 某些查询形式中的已翻译 URI。通过 URI（contentNode(id: "/de/some-slug/", idType: URI)）获取已翻译的文章时，请验证返回的 URI 是否与该语言中发布的内容匹配——某些查询形式会返回不一致的路径。在将其连接到路由之前，请在 GraphQL IDE 中进行测试。
  • 没有 language 参数的 ACF Options Pages 会回退到默认语言。在多语言网站上进行 Options Page 查询时，请始终传递 language。

如果您遇到此处未列出的集成问题，WPML 支持团队将全天候（24/7）为您解决 WPGraphQL 堆栈中 WPML 方面的问题。

作者：Amir

作者：Amir