Cách truy vấn nội dung đa ngôn ngữ bằng WPGraphQL – lọc ngôn ngữ và bản dịch

Trước khi bạn bắt đầu

Cài đặt và kích hoạt các plugin này:

• WPGraphQL (plugin mã nguồn mở từ dự án WPGraphQL).
• WPML và WPML Dịch Chuỗi.
• WPML GraphQL (tiện ích bổ sung mà trang này đề cập).

Nếu bạn cũng sử dụng Advanced Custom Fields:

• Advanced Custom Fields Multilingual (ACFML).
• WPGraphQL for Advanced Custom Fields (từ dự án WPGraphQL).

Nội dung nguồn của bạn cần được dịch trong WPML trước khi các truy vấn bên dưới có thể trả về bất kỳ kết quả nào. Khi bật Dịch mọi thứ tự động (mặc định của WPML 5), các bản dịch sẽ được tạo trong nền khi bạn xuất bản nội dung. Đối với thiết lập thủ công, hãy gửi nội dung để dịch từ WPML → Bảng điều khiển → dịch thuật. Các bài viết và thuật ngữ đã dịch là những gì mà các truy vấn GraphQL bên dưới sẽ lọc và trả về.

GraphQL IDE – nơi kiểm tra các truy vấn

WPGraphQL thêm một màn hình GraphQL → GraphQL IDE vào trang quản trị WordPress. Query Composer của IDE liệt kê mọi trường có sẵn, bao gồm đối số language và trường translations của WPML, đồng thời chạy các truy vấn trên trang web chính thức của bạn. Hãy kiểm tra các truy vấn ở đó trước khi tích hợp chúng vào framework giao diện người dùng của bạn.

Endpoint GraphQL cho mỗi ngôn ngữ

WPGraphQL phản hồi tại /graphql. Một truy vấn không có đối số language sẽ trả về nội dung bằng ngôn ngữ mặc định của bạn. Để lấy nội dung bằng một ngôn ngữ khác, hãy thêm where: { language: "es" } vào truy vấn.

Truy vấn nội dung theo ngôn ngữ

Thêm where: { language: "<code>" } vào bất kỳ truy vấn danh sách nào: bài viết, loại nội dung tùy chỉnh, thuật ngữ phân loại, menu, mục menu, bình luận. Mã ngôn ngữ là cùng một mã mà WPML sử dụng ở mọi nơi (en, es, fr, pt-pt, v.v.). Truyền language: "all" để trả về nội dung từ mọi ngôn ngữ cùng một lúc.

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

Khi một node cấp cao nhất được lọc theo ngôn ngữ, các mục được kết nối (chuyên mục, thẻ, phân loại tùy chỉnh) sẽ tự động tuân theo cùng một ngôn ngữ đó. Truy vấn trên trả về các bài viết bằng tiếng Tây Ban Nha với các chuyên mục bằng tiếng Tây Ban Nha, không cần thêm đối số nào.

Lấy mọi bản dịch của một node trong một truy vấn

Thêm trường translations vào bất kỳ truy vấn bài viết hoặc phân loại nào để trả về các phiên bản ngôn ngữ khác của node trong cùng một payload:

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

Mỗi bài viết được trả về với các trường tiếng Anh của nó cộng với một mảng chứa các slug và URI của các ngôn ngữ khác. Đó là cấu trúc mà một bộ chuyển đổi ngôn ngữ hiển thị bên cạnh nội dung trang sử dụng: một yêu cầu, mọi lựa chọn thay thế mà khách truy cập có thể chuyển sang.

Truy vấn một bài viết cụ thể theo ID hoặc slug bằng bất kỳ ngôn ngữ nào

Để lấy trực tiếp một bài viết đã dịch (theo slug đã dịch hoặc theo ID cơ sở dữ liệu), hãy sử dụng truy vấn post số ít với 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 }
  }
}

Cả hai truy vấn đều trả về bài viết đã dịch (tiêu đề, slug, URI) mà không cần lọc thêm ở giao diện người dùng.

Menu đa ngôn ngữ

Truy vấn các menu và mục menu theo ngôn ngữ với cùng một đối số where: { language }. Để lấy các mục của một vị trí menu trong giao diện, hãy thêm cả vị trí đó:

query NavES {
  menuItems(where: { language: "es", location: PRIMARY }) {
    nodes {
      label
      url
      path
    }
  }
}

Để liệt kê các menu của một ngôn ngữ, hãy sử dụng truy vấn menus:

query MenusES {
  menus(where: { language: "es" }) {
    nodes {
      name
      locations
    }
  }
}

label và url của mỗi mục menu được trả về bằng ngôn ngữ được truy vấn. Các mục menu liên kết đến các bài viết đã dịch sẽ tự động phân giải thành URI đã dịch. Truy vấn menu số ít không có đối số language, vì vậy hãy sử dụng menus hoặc menuItems để chọn ngôn ngữ.

Các ngôn ngữ đã cài đặt – dành cho bộ chuyển đổi ngôn ngữ

Đối với bộ chuyển đổi ngôn ngữ toàn cục (độc lập với bất kỳ bài viết đơn lẻ nào), hãy sử dụng các truy vấn languages và defaultLanguage để liệt kê mọi ngôn ngữ trên trang web:

query SiteLanguages {
  languages {
    code
    country_flag_url
    default_locale
    native_name
    translated_name
    url
  }
  defaultLanguage {
    code
    native_name
  }
}

Trả về một node cho mỗi ngôn ngữ đang hoạt động với URL cờ, tên bản địa, tên đã dịch và URL trang chủ của ngôn ngữ. Đó là đủ dữ liệu để hiển thị một bộ chuyển đổi có cờ và nhãn mà không cần hard-code danh sách ngôn ngữ.

Truy vấn các trường tùy chỉnh ACF theo ngôn ngữ

Khi ACFML và WPGraphQL for ACF đang hoạt động, các trường ACF trên một bài viết hoặc loại nội dung tùy chỉnh sẽ trả về các giá trị được lưu trên bài viết đó. Mỗi bản dịch có các giá trị riêng, vì vậy hãy truy vấn bài viết bằng ngôn ngữ bạn cần. Không cần thêm đối số nào.

Đối với ACF Options Pages, vốn không bị ràng buộc với một bài viết đơn lẻ, hãy thêm đối số language vào truy vấn Options Page:

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

Đối số này yêu cầu một mã ngôn ngữ khớp với một trong các ngôn ngữ đang hoạt động trên trang web của bạn.

Kể từ WPGraphQL for ACF 3.0.0, một options page chỉ có trong lược đồ GraphQL khi bạn bật tùy chọn show_in_graphql cho nó. Nếu không có cài đặt này, truy vấn options page và đối số language của nó sẽ không tồn tại. Nếu bạn đăng ký options page trong mã, hãy thêm cài đặt ở đó:

acf_add_options_page( array(
  'page_title'         => 'Site Settings',
  'menu_slug'          => 'site-settings',
  'show_in_graphql'    => true,
  'graphql_field_name' => 'siteSettings',
) );

Chi tiết tác giả đã dịch

WPML GraphQL trả về firstName, lastName, nickname và description đã dịch của người dùng. Để dịch chúng:

1. Truy cập trang WPML → Dịch chuỗi.
2. Trong tùy chọn Translate User properties, hãy chọn các vai trò người dùng và lưu lại.
3. Dịch các chuỗi trong domain Authors.

Các hạn chế đã ghi nhận và giải pháp tạm thời

• Các URI đã dịch trong một số cấu trúc truy vấn. Khi lấy một bài viết đã dịch theo URI (contentNode(id: "/de/some-slug/", idType: URI)), hãy xác minh URI được trả về khớp với những gì được xuất bản trong ngôn ngữ đó – một số cấu trúc truy vấn trả về các đường dẫn không nhất quán. Hãy kiểm tra trong GraphQL IDE trước khi tích hợp vào định tuyến.
• Các ACF Options Pages không có đối số language sẽ lùi về ngôn ngữ mặc định. Luôn truyền language cho các truy vấn Options Page trên các trang web đa ngôn ngữ.

Nếu bạn gặp sự cố tích hợp không được liệt kê ở đây, nhóm hỗ trợ WPML sẽ hỗ trợ phần WPML của ngăn xếp WPGraphQL 24/7.