Cách dịch các trường tùy chỉnh ACF trong WordPress – Nhóm trường, Repeater, Trang tùy chọn

Trước khi bắt đầu

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

• Advanced Custom Fields hoặc ACF Pro.
• WPML và WPML Dịch Chuỗi.
• ACFML (tiện ích bổ sung mà trang này đề cập).

Các Nhóm trường phải được cấu hình sẵn trong ACF. Bạn có thể thay đổi tùy chọn dịch cho từng trường sau đó, vì vậy thứ tự thực hiện không quan trọng. Thiết lập các Nhóm trường, sau đó quay lại ACFML.

Chọn chế độ dịch cho mỗi Nhóm trường

Không phải Nhóm trường ACF nào cũng hoạt động giống nhau khi dịch. ACFML cung cấp ba chế độ cho mỗi Nhóm trường, được thiết lập trong ACF > Nhóm trường, tại phần Thiết lập đa ngôn ngữ:

Các trường giống nhau trên các ngôn ngữ

Cài đặt điển hình cho hầu hết các trang web ACF. Dịch các giá trị trường sang từng ngôn ngữ trong khi cấu trúc vẫn giữ nguyên. Trang Đội ngũ của chúng tôi là ví dụ kinh điển. Đội ngũ của bạn giống nhau ở mọi ngôn ngữ, vì vậy tên và tiểu sử của mỗi thành viên trong đội ngũ được dịch theo từng ngôn ngữ trong khi cấu trúc trường vẫn nguyên vẹn. Bạn nhập thông tin đội ngũ bằng ngôn ngữ nguồn, sau đó gửi bài viết để dịch thông qua WPML > Bản dịch > Bảng điều khiển; các giá trị đã dịch sẽ được trả về và đính kèm vào các trường tương ứng.

Các trường khác nhau trên các ngôn ngữ

Sử dụng khi mỗi ngôn ngữ hiển thị nội dung hoàn toàn khác nhau trong cùng một Nhóm trường. Trường hợp kinh điển là một công ty tổ chức các sự kiện được bản địa hóa. Trang Sự kiện tiếng Anh hiển thị các sự kiện dành cho khán giả nói tiếng Anh, trang tiếng Pháp hiển thị các sự kiện dành cho khán giả nói tiếng Pháp. Đặt Nhóm trường thành Các trường khác nhau trên các ngôn ngữ, sau đó mở bài viết bạn muốn bản địa hóa > trong hộp Ngôn ngữ ở bên phải, nhấp vào biểu tượng dấu cộng cho ngôn ngữ đích > một bản nháp trống sẽ mở ra với các trường tùy chỉnh trống > điền các giá trị dành riêng cho ngôn ngữ đó và xuất bản.

Chế độ chuyên gia

Sử dụng khi bạn cần kết hợp: một số trường được dịch theo ngôn ngữ, các trường khác giữ nguyên, các trường khác sao chép một lần rồi thay đổi độc lập. Chọn Chế độ chuyên gia trong thiết lập Nhóm trường và đặt tùy chọn cho từng trường. Ví dụ về Sự kiện với hành vi hỗn hợp: tiêu đề và mô tả được đặt thành Dịch; giá, ngày và địa chỉ được đặt thành Sao chép.

Tùy chọn dịch cho từng loại trường ACF

Mỗi trường trong một Nhóm trường có một trong bốn tùy chọn dịch:

• Dịch. Giá trị của trường được dịch theo từng ngôn ngữ.
• Sao chép. Giá trị của trường được đồng bộ hóa trên các ngôn ngữ; chỉnh sửa một lần và nó sẽ tự động cập nhật.
• Sao chép một lần. Giá trị của trường được dùng làm điểm khởi đầu cho bản dịch, sau đó mỗi phiên bản ngôn ngữ có thể được chỉnh sửa độc lập.
• Không dịch. Trường bị bỏ qua trong quá trình dịch.

Khi bạn chọn Các trường giống nhau trên các ngôn ngữ hoặc Các trường khác nhau trên các ngôn ngữ, mỗi trường sẽ có một tùy chọn mặc định hợp lý tùy theo loại trường. Các bảng dưới đây hiển thị những mặc định đó. Sử dụng Chế độ chuyên gia để ghi đè chúng cho từng trường, hoặc sử dụng bộ lọc acfml_field_group_mode_field_translation_preference để ghi đè mặc định cho một loại trường trên toàn trang web (xem Các hook dành cho nhà phát triển cho các trường hợp ngoại lệ bên dưới).

Repeater và Flexible Content – Sao chép hoặc Sao chép một lần

Đối với các trường Repeater và Flexible Content, bạn chọn giữa hai hành vi ở cấp độ hàng trước khi các tùy chọn của trường con có hiệu lực:

• Sao chép. Cùng bố cục và số lượng hàng ở mọi ngôn ngữ. Người dịch nhìn thấy các hàng giống nhau; các trường con được dịch theo tùy chọn riêng của chúng.
• Sao chép một lần. Mỗi ngôn ngữ có thể có một bố cục khác nhau và số lượng hàng khác nhau sau lần khởi tạo ban đầu.

Chọn Sao chép khi cấu trúc giống nhau trên các ngôn ngữ (hầu hết các trường hợp). Chọn Sao chép một lần khi các phiên bản ngôn ngữ có cấu trúc khác nhau (ví dụ: một danh sách sự kiện khác nhau cho mỗi ngôn ngữ).

Các trường cơ bản

Các trường nội dung

Các trường lựa chọn

Các trường jQuery

Các trường bố cục

Các trường quan hệ

Thiết lập tùy chọn cho các trường được đăng ký bằng PHP hoặc JSON

Các Nhóm trường ACF được đăng ký bằng PHP (thông qua acf_add_local_field_group()) hoặc thông qua tính năng Local JSON của ACF không nhận các tùy chọn dịch từ giao diện quản trị, vì trang quản trị không quản lý chúng. Hãy thiết lập các tùy chọn ở cùng nơi bạn đăng ký các trường.

Đối với mỗi trường trong định nghĩa nhóm trường, hãy thêm một khóa wpml_cf_preferences. Giá trị là một số nguyên tương ứng với bốn tùy chọn dịch: 0 cho Không dịch (WPML bỏ qua trường này), 1 cho Sao chép (giá trị được đồng bộ hóa trên các ngôn ngữ), 2 cho Dịch (giá trị sẽ được đưa vào quá trình dịch), và 3 cho Sao chép một lần (giá trị được sao chép sang các bản dịch mới, sau đó mỗi ngôn ngữ có thể được chỉnh sửa độc lập).

Một ví dụ tối giản:

acf_add_local_field_group( [
    'key'    => 'group_1',
    'title'  => 'My Group',
    'fields' => [
        [
            'key'                 => 'field_1',
            'label'               => 'Sub Title',
            'name'                => 'sub_title',
            'type'                => 'text',
            'wpml_cf_preferences' => 2, // Translate.
        ],
    ],
    // ...rest of the field-group config
] );

Sau khi bạn định nghĩa các trường trong mã, hãy đồng bộ hóa các tùy chọn vào WPML để trang quản trị nhận diện chúng:

1. Truy cập ACF > Công cụ.
2. Cuộn đến Translate ACF Local JSON and PHP-Registered Fields.
3. Trong phần Sync Translation Preferences for Local Fields, chọn Sync once now và nhấp vào Apply.

WPML đọc các tùy chọn từ các định nghĩa PHP của bạn và lưu trữ chúng. Quá trình đồng bộ chạy một lần khi bạn kích hoạt nó, không phải trên mỗi lần tải trang.

Nếu bạn sử dụng tính năng Local JSON của ACF để chia sẻ các nhóm trường giữa các trang web, ACFML sẽ tự động ghi các tùy chọn dịch vào các tệp JSON. Xuất tệp JSON từ một trang web, nhập nó vào trang web khác và trang web đích sẽ nhận các tùy chọn ngay khi ACFML được kích hoạt ở cả hai bên.

Dịch các nhãn trường ACF

Nhãn trường ACF là các tên xác định từng trường tùy chỉnh trong trình soạn thảo WordPress và trên front-end (ví dụ: Số điện thoại, Địa chỉ). Chúng được dịch riêng biệt với các giá trị trường và chúng nằm trong WPML Dịch Chuỗi, không phải trong công việc dịch thuật của bài viết.

Để gửi các nhãn trường đi dịch:

1. Mở WPML > Bản dịch > Bảng điều khiển.
2. Mở rộng phần ACF Field Group.
3. Chọn mục Field Group Labels cho Nhóm trường bạn muốn dịch.
4. Chọn một phương pháp dịch (PTC, người dịch của bạn, hoặc Tự dịch) và gửi.

Các nhãn đã dịch sẽ tự động xuất hiện trên front-end ngay khi bản dịch hoàn tất.

Dịch các lựa chọn trường ACF

Các trường lựa chọn (Select, Checkbox, Radio Button, Button Group) mang các nhãn tùy chọn riêng của chúng (ví dụ: Nhỏ / Trung bình / Lớn). Các nhãn này cũng nằm cùng với các nhãn trường thay vì bên trong bản dịch bài viết. Hãy gửi chúng theo cùng một cách:

1. Mở WPML > Bản dịch > Bảng điều khiển.
2. Mở rộng phần ACF Field Group.
3. Chọn Nhóm trường có các giá trị lựa chọn mà bạn muốn dịch.
4. Chọn một phương pháp dịch và gửi.

Dịch các Trang tùy chọn ACF

Các Trang tùy chọn ACF (các màn hình cài đặt toàn cục như Chi tiết liên hệ, Cài đặt header, Liên kết chân trang) được dịch dưới dạng loại đối tượng riêng của chúng, tách biệt với các bài viết:

1. Mở WPML > Bản dịch > Bảng điều khiển.
2. Mở rộng phần ACF Options.
3. Chọn Trang tùy chọn bạn muốn dịch.
4. Chọn một phương pháp dịch và gửi.

Các giá trị Trang tùy chọn của mỗi ngôn ngữ sẽ tự động xuất hiện khi ACF đọc tùy chọn trong ngữ cảnh của ngôn ngữ đó.

Các vấn đề thường gặp

• Các nhãn trường có vẻ như chưa được dịch. Chúng nằm trong Dịch chuỗi, không phải trong bản dịch bài viết. Gửi mục Field Group Labels của Nhóm trường từ Bảng điều khiển (xem phần Dịch các nhãn trường ACF ở trên).
• Các giá trị lựa chọn có vẻ như chưa được dịch. Tình huống tương tự. Gửi Nhóm trường từ phần ACF Field Group của Bảng điều khiển để các giá trị tùy chọn được đưa vào.
• Các hàng Repeater không đồng bộ. Nhiều khả năng trường đang được đặt thành Sao chép một lần, trong khi Sao chép mới giữ cho các hàng khớp nhau. Mở Nhóm trường > chuyển hành vi của trường Repeater thành Sao chép.
• Logic điều kiện hoạt động không như mong đợi. Khi trường điều khiển được đặt thành Sao chép hoặc Không dịch, hành vi điều kiện tuân theo giá trị ngôn ngữ nguồn trên tất cả các bản dịch. Đặt trường điều khiển thành Dịch nếu giá trị của nó cần khác nhau theo từng ngôn ngữ.
• Các trường cục bộ (được đăng ký bằng PHP) bỏ qua các tùy chọn dịch được thiết lập trong trang quản trị. Đặt khóa wpml_cf_preferences trong chính định nghĩa nhóm trường và đồng bộ hóa từ ACF > Công cụ. Quy trình nằm trong phần Thiết lập tùy chọn cho các trường được đăng ký bằng PHP hoặc JSON ở trên. ACFML 2.2.0 (tháng 2 năm 2026) đã thêm hỗ trợ đầy đủ cho các Trường cục bộ; các phiên bản cũ hơn có những hạn chế ở điểm này.

Các hook dành cho nhà phát triển cho các trường hợp ngoại lệ

Để kiểm soát bằng lập trình (loại trừ các trường cụ thể khỏi quá trình dịch, ghi đè tùy chọn mặc định cho một loại trường trên toàn trang web, ẩn các chú thích khỏi người dịch, hoặc loại trừ các chuỗi nhóm trường khỏi các công việc dịch thuật bài viết), ACFML cung cấp hai bộ lọc và bốn hằng số. Tài liệu tham khảo đầy đủ với các ví dụ mã nguồn có tại Tài liệu tham khảo về các hook và hằng số ACFML.