如何使用 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 会在 WordPress 管理后台中添加一个 GraphQL > GraphQL IDE 屏幕。该 IDE 的 Query Composer 列出了每个可用的字段，包括 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 中进行测试。
• 没有 language 参数的 ACF 选项页面会回退到默认语言。在多语言网站上进行选项页面查询时，请始终传递 language。

如果您遇到此处未列出的集成问题，WPML 支持团队将提供 24/7 全天候的 WPGraphQL 堆栈 WPML 端支持。