Đăng ký widget tùy chỉnh của trình tạo trang để dịch

Để đăng ký các widget tùy chỉnh của trình tạo trang để dịch, bạn cần sử dụng tệp wpml-config.xml. Hãy làm theo hướng dẫn này để tìm hiểu cách sử dụng tệp đó.

Hướng dẫn này dành cho các nhà phát triển xây dựng giao diện và plugin hoặc thêm mã trình tạo trang tùy chỉnh vào trang web của họ.

Nếu bạn sử dụng trình tạo trang của bên thứ ba và không thể dịch các widget tùy chỉnh trên trang web của mình, vui lòng liên hệ với bộ phận hỗ trợ của WPML.

Các trình tạo trang như Elementor, Beaver Builder, SiteOrigin và Cornerstone đi kèm với một bộ widget riêng của chúng. Các widget mặc định này hoạt động trơn tru với WPML.

Đôi khi, bạn có thể tạo các widget tùy chỉnh nhằm mục đích sử dụng với các trình tạo trang này hoặc các trình tạo trang khác.

Widget tùy chỉnh là bất kỳ widget bổ sung, độc đáo nào không được đóng gói kèm theo trình tạo trang. Chúng có thể được tạo bởi nhóm phát triển của bạn, các nhà phát triển bên thứ ba hoặc đến từ các plugin và giao diện khác.

Widget tùy chỉnh cũng là bất kỳ widget nào đến từ các plugin tiện ích bổ sung được phát triển riêng cho một trình tạo trang, như Elementor, bởi các nhà phát triển bên ngoài.

Khi nào tôi cần đăng ký các widget tùy chỉnh để dịch?

Bạn cần đăng ký widget tùy chỉnh của mình để dịch:

Nếu đó là một widget không được cung cấp ban đầu bởi một trình tạo trang
Nếu bạn đã tạo và thêm nó thông qua một plugin hoặc giao diện khác
Nếu nó được phát triển cho các trang web WordPress của bạn hoặc một trình tạo trang cụ thể bởi nhóm của bạn hoặc các bên thứ ba

Trước đây, cách phổ biến nhất để đăng ký các widget tùy chỉnh để dịch là sử dụng mã PHP tùy chỉnh. Giờ đây, bạn có thể dễ dàng đăng ký widget để dịch bằng cách sử dụng wpml-config.xml, tệp cấu hình của WPML.

Đăng ký các widget Elementor tùy chỉnh để dịch trong WPML 4.9+

Trong WPML 4.9 trở lên, WPML tự động nhận diện các widget Elementor tùy chỉnh và làm cho chúng có thể dịch được. Tuy nhiên, nó có thể đăng ký các chuỗi văn bản mà bạn không muốn dịch.

Đó là lý do tại sao chúng tôi đặc biệt khuyên bạn vẫn nên cấu hình thủ công tệp wpml-config.xml như được mô tả trên trang này. Điều này cho phép bạn kiểm soát các trường nào có thể dịch được.

Cách đăng ký các widget Elementor tùy chỉnh và khối Gutenberg để dịch bằng plugin Multilingual Tools

Plugin Multilingual Tools của chúng tôi bao gồm một WPML – Config Generator dành cho Elementor và các khối Gutenberg. Tính năng này cho phép bạn thêm bất kỳ widget Elementor tùy chỉnh hoặc khối Gutenberg nào mà bạn muốn đăng ký để dịch vào một trang. Sau đó, nó sẽ tự động tạo phiên bản đầu tiên của mã XML mà bạn cần.

Tìm hiểu cách đăng ký các widget Elementor tùy chỉnh để dịch và cách làm cho các khối Gutenberg có thể dịch được.

Để có thể đăng ký một widget tùy chỉnh trong tệp wpml-config.xml, trước tiên bạn cần tìm một số thông tin cơ bản về nó.

Bạn có thể dễ dàng lấy thông tin này bằng cách sử dụng một plugin như JSM Show Post Metadata. Plugin này hiển thị siêu dữ liệu bài viết và các giá trị chưa được tuần tự hóa của chúng trong một hộp meta ở cuối các trang chỉnh sửa bài viết.

Ngoài ra, bạn có thể sử dụng các bước sau để lấy thông tin này:

Truy cập trang WPML → Cài đặt, cuộn đến phần Dịch trường tùy chỉnh và nhấp vào liên kết Hiển thị trường hệ thống.
Đặt trường tùy chỉnh _elementor_data thành Dịch.
Tạo một trang mới và chỉ thêm widget Elementor mà bạn muốn đăng ký. Lưu trang.
Truy cập WPML → Cài đặt và trong phần Trình biên tập dịch thuật, tạm thời kích hoạt tùy chọn Trình biên tập dịch thuật cổ điển.
Hãy thử dịch trang bạn đã tạo ở Bước 3 bằng Trình biên tập dịch thuật cổ điển và bạn sẽ nhận thấy một mảng đã được tuần tự hóa, giống như thế này:

Sao chép dữ liệu widget trong Trình biên tập cổ điển — Mảng đã được tuần tự hóa của widget Elementor hiển thị trong Trình biên tập dịch thuật cổ điển của WPML

Sao chép nội dung của mảng đã được tuần tự hóa.
Sử dụng công cụ giải tuần tự hóa ưa thích của bạn để xem rõ hơn cách widget xuất nội dung của nó. Trong trường hợp của chúng tôi, chúng tôi đã sử dụng trang web Unserialize.

Dưới đây là phần giải thích về nội dung của mảng mà bạn sẽ thấy:

[widgetType] chứa tên được chèn vào thuộc tính name của thẻ widget.
Các trường thực tế sẽ nằm bên trong một Mảng và bạn có thể tìm thấy chúng bằng cách tìm kiếm [0], thao tác này sẽ hiển thị nội dung của phần tử đầu tiên trong mảng.
Giá trị field sẽ là tên nằm trong ngoặc vuông chứa tên của trường. Ví dụ: [title] => this is a field title. Trong trường hợp này, “title” là văn bản bạn cần.
“Items of” sẽ lấy giá trị của nó từ phần tử tạo ra mảng. Ví dụ: [contents]=> array. Trong trường hợp này, “contents” là văn bản bạn cần.

Khi bạn đã có thông tin này, bạn có thể tiến hành đăng ký thực tế widget để dịch.

Đăng ký các widget đơn giản

Video sau đây sẽ hướng dẫn bạn qua một ví dụ về cách đăng ký một widget Elementor đơn giản:

Ví dụ sau đây minh họa cách đăng ký một widget đơn giản. Widget đơn giản ở đây có nghĩa là widget không có các trường lặp lại.

<wpml-config>
	<elementor-widgets>
		<widget name="heading">
			<conditions>
				<condition key="widgetType">heading</condition>
			</conditions>
			<fields>
				<field type="Heading" editor_type="LINE">title</field>
				<field type="Heading: Link URL" editor_type="LINK">link>url</field>
			</fields>
		</widget>
	</elementor-widgets>
</wpml-config>

Hãy cùng xem qua cấu trúc của ví dụ đã cho:

Bắt đầu với thẻ <elementor-widgets>. Thẻ này cho WPML biết bạn sẽ đăng ký các widget của trình tạo trang nào. Nó có thể là một trong những thẻ sau:
- <elementor-widgets>: thẻ này phải được sử dụng nếu bạn đang sử dụng Elementor, Elementor PRO hoặc bất kỳ tiện ích bổ sung nào khác của Elementor.
- <beaver-builder-widgets>: thẻ này phải được sử dụng nếu bạn đang sử dụng Beaver Builder Lite, Beaver Builder cao cấp hoặc bất kỳ tiện ích bổ sung nào khác của Beaver Builder.
- <siteorigin-widgets>: thẻ này phải được sử dụng nếu bạn đang sử dụng trình tạo trang SiteOrigin.
- <cornerstone-widgets>: và thẻ này phải được sử dụng cho trình tạo trang Cornerstone đi kèm với giao diện X hoặc giao diện PRO.
Thêm các widget của bạn:
- <widget name="widget_name"> trong đó widget_name là tên được sử dụng để đăng ký widget trong trình tạo trang.
- <conditions> (tùy chọn): trong các điều kiện, bạn thêm một điều kiện với khóa bằng với tên widget. Nó có thể được sử dụng khi tên widget khác với khóa widget trong dữ liệu, nhưng thường thì không cần thiết.

Thêm các trường của widget, bọc chúng trong thẻ <fields>:
- field: ID của trường. ID này giống với ID được sử dụng khi thêm một control thông qua hàm Control_stack::add_control.
- type (tùy chọn): Loại trường. Đây là văn bản được hiển thị trong Trình biên tập dịch thuật nâng cao hoặc Trình biên tập dịch thuật cổ điển của WPML để giúp người dịch biết trường nào đang được dịch.
- editor_type (tùy chọn): Đây là loại trường văn bản được sử dụng trong Trình biên tập dịch thuật cổ điển của WPML. Các giá trị hợp lệ là LINE, AREA, LINK, và VISUAL. Nó mặc định là LINE nếu bị thiếu.
- key_of (tùy chọn): Thuộc tính này chỉ được sử dụng cho các thẻ <field> có chứa một mảng bên trong thẻ <fields-in-item>.

Bạn có thể sử dụng các phần tử này để đăng ký một widget đơn giản với bất kỳ số lượng trường nào.

Đăng ký các trường có ID bài viết hoặc ID phân loại

Trong phần trên, bạn đã biết rằng thuộc tính type thường được sử dụng để hiển thị văn bản mô tả trong Trình biên tập dịch thuật.

Tuy nhiên, khi các trường widget của bạn lưu trữ ID bài viết hoặc ID phân loại (chẳng hạn như hình ảnh đã chọn, bài viết liên quan hoặc danh mục đã chọn), bạn sử dụng các giá trị đặc biệt để kích hoạt chuyển đổi tự động:

type="post-ids" – dành cho các trường chứa ID bài viết
type="term-ids" – dành cho các trường chứa ID phân loại/thuật ngữ

Khi bạn sử dụng các giá trị types này:

Trường sẽ không xuất hiện trong trình biên tập dịch thuật
WPML tự động chuyển đổi các ID để trỏ đến nội dung đã dịch tương ứng
Hỗ trợ cả ID đơn lẻ và danh sách các ID được phân tách bằng dấu phẩy

Ví dụ:

<wpml-config>
    <elementor-widgets>
        <widget name="the-widget-name">
            <fields>
                <field type="post-ids" sub-type="attachment">image_id</field>
                <field type="post-ids" sub-type="post">selected_posts</field>
                <field type="term-ids" sub-type="category">category_filter</field>
            </fields>
        </widget>
    </elementor-widgets>
</wpml-config>

Trong ví dụ này, thuộc tính sub-type tùy chọn chỉ định chính xác loại bài viết hoặc phân loại đang được chuyển đổi:

Đối với type="post-ids": sử dụng sub-type="attachment", sub-type="post", sub-type="page" hoặc slug loại bài viết tùy chỉnh của bạn
Đối với type="term-ids": sử dụng sub-type="category", sub-type="post_tag" hoặc slug phân loại tùy chỉnh của bạn

Việc thêm sub-type giúp cải thiện hiệu suất bằng cách tránh các truy vấn cơ sở dữ liệu bổ sung để xác định loại nội dung.

Để xem thêm các ví dụ, hãy xem tệp cấu hình của Elementor và tìm kiếm post-ids.

Đăng ký các widget có trường lặp lại

Video sau đây sẽ hướng dẫn bạn qua một ví dụ về cách đăng ký một widget Elementor nâng cao với các trường lặp lại:

A hotspot widget's fields in the Advanced Translation Editor

Đối với các widget có trường lặp lại, bạn cần bọc các trường trong thẻ <fields-in-item items_of="tabs"> (trong đó tabs là tên của widget có các trường lặp lại). Hãy xem ví dụ này:

<widget name="accordion">
	<fields-in-item items_of="tabs">
		<field type="Accordion: Title" editor_type="LINE">tab_title</field>
		<field type="Accordion: Content" editor_type="VISUAL">tab_content</field>
	</fields-in-item>
</widget>

Trong một số trường hợp, widget có thể có nhiều trường lặp lại. Hãy xem xét cấu trúc dữ liệu sau từ widget Table của Ultimate Addons for Elementor làm ví dụ:

Cấu trúc dữ liệu của một widget Table từ Ultimate Addons for Elementor

Để đăng ký widget này, vui lòng xem ví dụ sau:

<widget name="uael-table">
	<fields-in-item items_of="table_content">
		<field type="The Cell text" editor_type="LINE">cell_text</field>
	</fields-in-item>
	<fields-in-item items_of="table_headings">
		<field type="The Heading text" editor_type="LINE">heading_text</field>
	</fields-in-item>
</widget>

Đăng ký các widget có cả trường đơn giản và trường lặp lại

Lưu ý, các widget có thể có cả hai loại: fields và fields-in-item. Hãy xem ví dụ này về một widget sử dụng cả hai:

<widget name="price-table">
	<fields>
		<field type="Price Table: Heading" editor_type="LINE">heading</field>
		<!-- ... -->
	</fields>
	<fields-in-item items_of="features_list">
		<field type="Price table: text" editor_type="LINE">item_text</field>
	</fields-in-item>
</widget>

Nhóm các trường để tổ chức tốt hơn

Để cải thiện độ rõ ràng và tính tổ chức của cấu hình XML của bạn, bạn có thể thêm tiền tố là tên nhóm vào nhãn trường. Hãy xem xét ví dụ này về một widget hotspot:

<widget name="hotspot">
    <fields-in-item items_of="hotspot">
        <field type="Hotspot: Label">hotspot_label</field>
        <field type="Hotspot: URL" key_of="hotspot_link">url</field>
        <field type="Hotspot: Content" editor_type="VISUAL">hotspot_tooltip_content</field>
    </fields-in-item>
</widget>

Ở đây, mỗi trường trong widget hotspot được thêm tiền tố bằng nhãn Hotspot:. Tiền tố này cũng xuất hiện trong Trình biên tập dịch thuật nâng cao, giúp dễ dàng xác định và dịch từng trường hơn:

Dịch widget hotspot trong Trình biên tập dịch thuật nâng cao

Đăng ký các loại nội dung khác của trình tạo trang

Xem tài liệu của chúng tôi về cách đăng ký nội dung của trình tạo trang trong tệp cấu hình ngôn ngữ của bạn để biết thêm về cách đăng ký chuỗi văn bản, shortcode và hơn thế nữa.

Các tài nguyên bổ sung

Để tìm hiểu thêm về tệp wpml-config.xml, hãy truy cập hướng dẫn về Tệp cấu hình ngôn ngữ.

Để tùy chỉnh các phần tử khác bằng tệp wpml-config.xml, hãy truy cập các hướng dẫn bổ sung của chúng tôi:

Đăng ký các widget tùy chỉnh của trình tạo trang để dịch