WPML GraphQL - 适用于无头 WordPress 的多语言 WPGraphQL

从前端按语言查询内容

每个 WPGraphQL 查询都会获得一个 language 参数。在一个字段中按语言筛选文章、自定义文章类型、分类法术语、菜单、菜单项和评论 —— 无需在前端进行查询后筛选，不会使请求量翻倍，也无需猜测语言。

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

当您按语言筛选顶级节点时，关联的项目（类别、标签、自定义分类法）会自动遵循相同的语言。无需为每个嵌套字段提供额外参数，结果即可保持一致。

想要为 XML 站点地图或总计数获取所有内容而不管语言如何？请传递 language: "all"。

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

文章和分类法术语上的 translations 字段会返回节点的每种其他语言版本：别名、URI、语言代码以及您请求的任何嵌套字段。一次查询，一次往返，即可获取页面的所有语言版本。

这就是在页面内容旁边渲染语言切换器所需的数据，而无需让前端执行一连串的相关查询。

多语言菜单、分类法、评论和语言数据

除了文章之外，WPML GraphQL 还将相同的 language 参数和翻译处理扩展到：

菜单和菜单项。用于按语言导航的 menus(where: { language: "fr" }) 和 menuItems(where: { language: "fr" })。
分类法术语。类别、标签和自定义分类法默认遵循其文章的语言，并可以直接按语言进行查询。
评论。返回与特定语言的文章关联的评论。
languages 和 defaultLanguage 查询。列出网站上安装的每种语言及其代码、区域设置、本族语名称、国家/地区旗帜 URL 和主页 URL。这是自定义语言切换器所需的数据结构。

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

有两种查询形式可通过其特定于语言的标识符获取单篇已翻译的文章：

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

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

无论哪种形式都会返回已翻译的文章及其翻译后的标题、别名和 URI —— 前端无需单独执行“这是翻译吗？”的逻辑。

针对当前 WPGraphQL 版本进行维护

我们在 WPGraphQL 2.24.1 和 WPGraphQL for ACF 3.0.0 上测试了 WPML GraphQL 5.2.0。维护 WPGraphQL 的团队与我们密切合作，因此多语言层能够与架构保持同步更新。当 WPGraphQL 发布新版本时，WPML GraphQL 会紧随其后进行更新。

添加 ACFML 和 WPGraphQL for ACF 后即可与 ACF 配合使用

许多无头网站在 Advanced Custom Fields 中构建其内容模型，并通过 WPGraphQL 将其公开。添加 ACFML 和 WPGraphQL for ACF，您的 ACF 数据就会遵循与架构其余部分相同的语言规则。

查询任何语言的 ACF 选项页面

选项页面独立于任何文章之外，因此它们有自己的 language 参数。中继器和灵活内容中的子字段也会以该语言返回。以下查询读取 offices 中继器和 promos 灵活内容字段。从 WPGraphQL for ACF 3.0.0 开始，只有在为其开启 show_in_graphql 时，选项页面才会包含在架构中。

query StoreSettingsES {
  storeSettings(language: "es") {
    storeContact {
      heading
      offices { city openingHours }
      promos {
        ... on StoreContactPromosBannerLayout { bannerText }
      }
    }
  }
}

关系字段返回已翻译的文章

文章和自定义文章类型上的 ACF 字段没有自己的 language 参数。它们会遵循请求的语言。在以下查询中，where: { language: "es" } 为整个查询设置了该语言。

设置为复制的关系字段已经包含翻译后的 ID。当 WPML 将该字段复制到翻译时，ACFML 会将每个 ID 替换为其翻译。如果翻译尚不存在，则会保留原始 ID。您可以在 ACF 字段组编辑器的翻译首选项下为每个字段设置此首选项。请参阅我们翻译 ACF 自定义字段指南中的关系字段。

query BlendsES {
  posts(where: { language: "es" }) {
    nodes {
      title
      postExtras {
        relatedGuide {
          nodes { ... on Post { title languageCode } }
        }
      }
    }
  }
}

西班牙语文章会返回西班牙语指南。

请在每个请求中设置语言。通过 ID 或别名读取单篇文章的查询不包含 language 筛选器。然后它将在默认语言下运行，相关文章也会以默认语言返回。

如何设置语言取决于您的 WPML URL 格式。如果每种语言使用不同域名，请调用该语言的端点：https://es.example.com/graphql。如果使用语言参数，请将其添加到端点中：/graphql?lang=es。目录格式没有每种语言的专属端点，因此请在查询内部按语言进行筛选。

当缺少翻译时

WPML 不会回退到默认语言。如果相关文章在请求的语言中没有翻译，它将从结果中剔除：

{
  "data": {
    "posts": {
      "nodes": [
        {
          "title": "Nuestras mezclas de la casa",
          "postExtras": {
            "relatedGuide": {
              "nodes": [
                { "title": "Guía de compra de espresso", "languageCode": "es" }
              ]
            }
          }
        }
      ]
    }
  }
}

该字段指向两篇指南。其中只有一篇翻译成了西班牙语，因此西班牙语查询会返回一篇。您的前端将获得一个较短的列表，而绝不会出现混合语言。翻译缺失的文章后，它就会出现在同一个查询中。

当文章类型为可翻译时，列表将保持单一语言。如果您将文章类型设置为显示为已翻译，WPML 将以默认语言返回未翻译的指南。此时列表就会混合语言。

WPML GraphQL – 适用于无头 WordPress 的多语言 WPGraphQL