WPML

Làm cho các khối Gutenberg tùy chỉnh có thể dịch được

Đã cập nhật: ngày 5 tháng 6 năm 2025

Tìm hiểu cách chỉ định các khối Gutenberg tùy chỉnh nào bạn đã phát triển có thể dịch được. Bạn có thể thực hiện việc này bằng cách cấu hình tệp wpml-config.xml với sự trợ giúp của plugin thử nghiệm Multilingual Tools.

Hướng dẫn này dành cho các nhà phát triển tạo các khối tùy chỉnh của riêng họ cho Gutenberg. Nếu bạn không phải là tác giả plugin, hãy xem cách dịch nội dung được tạo bằng trình soạn thảo Gutenberg.

Bắt đầu

Để bắt đầu, hãy cài đặt và kích hoạt:

  1. Plugin lõi WPML
  2. WPML Dịch Chuỗi
  3. Multilingual Tools

Không nên sử dụng plugin Multilingual Tools trên các trang web đang hoạt động hoặc trang web chính thức. Chỉ sử dụng plugin này để thử nghiệm.

Tạo và thử nghiệm mã XML để đăng ký các khối Gutenberg cho dịch thuật

1. Tạo một bài viết hoặc trang mới và thêm các khối Gutenberg bạn muốn đăng ký. Đảm bảo thêm nội dung thử nghiệm vào mọi trường bạn muốn có thể dịch được, sau đó xuất bản.

Cuộn xuống phần WPML: Gutenberg Blocks và sao chép mã XML được tạo.

Sao chép mã XML được tạo sẵn để xem xét
Sao chép mã XML được tạo sẵn để xem xét

Quan trọng: Không nên sử dụng nguyên bản mã XML được tạo tự động. Bạn phải thử nghiệm và chỉnh sửa nó trước khi cung cấp cho người dùng của mình. Xem bước tiếp theo.

2. Truy cập WPML → Cài đặt và dán XML được tạo vào tab Cấu hình XML tùy chỉnh.

Đảm bảo xem xét kỹ mã được tạo tự động. Bạn có thể cần xóa một số trường không nhằm mục đích dịch, chẳng hạn như các trường cấu hình có giá trị cụ thể.

Lưu khi bạn đã sẵn sàng.

3. Quay lại trang bạn đã xuất bản và thực hiện các cập nhật nhỏ, như chỉnh sửa văn bản của nút hoặc tiêu đề.

Nhấp vào biểu tượng dấu cộng trong phần Ngôn ngữ để mở Trình biên tập dịch thuật nâng cao. Các trường từ các khối Gutenberg xuất hiện trong trình biên tập và có sẵn để dịch.

Kiểm tra các khối Gutenberg có thể dịch trong Trình biên tập dịch thuật nâng cao của WPML
Kiểm tra các khối Gutenberg có thể dịch trong Trình biên tập dịch thuật nâng cao của WPML

Khi bạn đã đăng ký các khối Gutenberg mà bạn muốn có thể dịch được, bạn có thể tạo tệp cấu hình ngôn ngữ của mình. Nếu bạn đã có, chỉ cần chỉnh sửa nó để thêm mã XML hoàn chỉnh của bạn.

Các ví dụ về việc đăng ký các khối Gutenberg có thể dịch được

Dịch hình ảnh

Giả sử bạn có một hình ảnh được hiển thị bằng mã sau:

Ví dụ về hình ảnh cần được dịch
<!-- wp:image {"id":3} -->
<figure class="wp-block-image"><img src="http://example.com/wp-content/uploads/2018/07/figure-2.png" alt="Image alt text" class="wp-image-3"/><figcaption>Image Caption</figcaption></figure>
<!-- /wp:image -->

Bạn muốn dịch các giá trị thuộc tính figcaption và alt của hình ảnh này.

Để đạt được điều này, bạn cần chèn mã sau vào wpml-config.xml:

Ví dụ về cài đặt để dịch khối Gutenberg
<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="core/image" translate="1">
        <xpath>//figure/figcaption</xpath>
        <xpath>//figure/img/@alt</xpath>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

Xin lưu ý rằng type là core/image chứ không phải wp:image vì đây là giá trị được trả về bởi API của khối.

Bạn có thể chỉ định các trường khối Gutenberg nào là liên kết. WPML sau đó sẽ thay thế bất kỳ liên kết nào bằng bản dịch của chúng nếu có.

Dịch các liên kết trong các khối Gutenberg
<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="core/some-block" translate="1">
        <xpath type="link">//a/@href</xpath>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

Dịch các thuộc tính của khối

Dưới đây là một ví dụ về định dạng cho định nghĩa của một khối trình soạn thảo:

Định dạng cho định nghĩa của một khối trình soạn thảo
<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="my-plugin/my-block" translate="1">
        <xpath label="My Block">//p</xpath>
        <key name="title" />
        <key name="foo">
            <key name="bar1" />
            <key name="bar2" />
        </key>
        <key name="/^[^_]\S+$/" search-method="regex" />
        <key name="something" search-method="wildcards" />
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

Bạn có thể sử dụng phần tử key theo cùng cách nó được sử dụng với cấu hình văn bản quản trị / wp_options. Điều này cũng có nghĩa là bạn có thể có các phần tử key bên trong các phần tử key cha.

Bạn có thể sử dụng thuộc tính label để thêm các nhãn tùy chỉnh tùy chọn hiển thị trong Trình biên tập dịch thuật nâng cao bên cạnh các phần tử khối. Khi thuộc tính label là một phần của thẻ gutenberg-block, nó sẽ được sử dụng làm nhãn dự phòng cho các phần tử của khối không có nhãn cụ thể được xác định.

Ví dụ về nhãn dự phòng
<wpml-config>
    <gutenberg-blocks>
        <gutenberg-block type="my-plugin/mybutton" translate="1" label="My fallback block label">
            <xpath>//span</xpath>
            <xpath>//a@href</xpath>
        </gutenberg-block>
    </gutenberg-blocks>
</wpml-config>

Thuộc tính search-method có thể có một trong hai giá trị:

  • wildcards (mặc định)
  • regex.

Bạn có thể sử dụng wildcards theo cùng cách như đối với văn bản quản trị. Điều này có nghĩa là dấu hoa thị (*) có thể được sử dụng trong thuộc tính name. Dưới đây là một ví dụ về một khối:

Ví dụ về một khối
<!-- wp:my-plugin/my-block
    {
        "myp": {
            "mypTitle":"The title",
            "mypContent":"The Content",
            "_mypSystem:"Meta attribute to not translate"
        }
    }
/-->

Bạn có thể thiết lập định nghĩa khối bằng cách sử dụng wildcard:

Định nghĩa khối bằng cách sử dụng wildcard
<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="my-plugin/my-block" translate="1">
      <key name="myp">
          <key name="myp*" />
      </key>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

Điều này sẽ cho phép bạn dịch “The title” và “The content” vì đây là những thuộc tính duy nhất bắt đầu bằng myp.

regex cho phép bạn có một biểu thức chính quy trong thuộc tính name. Điều này có thể cực kỳ hữu ích cho các cấu hình phức tạp. Dưới đây là một ví dụ về một khối:

Cấu hình phức tạp – ví dụ
<!-- wp:my-plugin/my-block
    {
        "data": {
            "title":"The title",
            "_title":"e980759463943209f6f1ae09a239e353",
            "content":"The Content",
            "_content":"1502a7b825dfe7b789c63830609f1701"
        }
    }
/-->

Bạn có thể thiết lập định nghĩa khối với một biểu thức chính quy:

Định nghĩa khối với một biểu thức chính quy
<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="my-plugin/my-block" translate="1">
        <key name="data">
            <key name="/^[^_]\S+$/" search-method="regex" />
        </key>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

Điều này sẽ cho phép bạn dịch “The title” và “The content” vì đây là những thuộc tính duy nhất không bắt đầu bằng dấu gạch dưới (_).

Một số plugin khối lưu dữ liệu trong chuỗi JSON được mã hóa URL bên trong thuộc tính của khối. Thuộc tính encoding cho phép bạn giải mã chuỗi và đăng ký các khóa phụ của nó để dịch.

Ví dụ: plugin LazyBlocks lưu trữ nội dung trường lặp trong một chuỗi JSON được mã hóa:

Ví dụ về khối LazyBlocks với chuỗi JSON được mã hóa URL
<!-- wp:lazyblock/testwpml {"name":"%5B%7B%22firstname%22:%22Shekhare%22,%22lastname%22:%22Bhandari%22%7D,%7B%22firstname%22:%22Compatibility%22,%22lastname%22:%22Escalation%22%7D%5D","blockId":"Z169b0O","blockUniqueClass":"lazyblock-testwpml-Z169b0O"} /-->

Bạn có thể đăng ký các khóa phụ firstname và lastname bằng cách sử dụng cấu hình XML sau:

Ví dụ về việc đăng ký các chuỗi JSON được mã hóa URL bên trong thuộc tính của khối
<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="lazyblock/team" translate="1">
      <key name="name" encoding="json">
        <key name="*">
          <key name="firstname" />
          <key name="lastname" />
        </key>
      </key>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

Để cho phép WPML tự động dịch các URL, bạn có thể khai báo các thuộc tính khối Gutenberg là các liên kết.

Dưới đây là ví dụ về một khối Gutenberg tùy chỉnh có liên kết có thể nhấp:

<!-- wp:foo/link {"label":"Click here!","url":"https://example.com/some-page/"} /-->

Để làm cho các thuộc tính label và url có thể dịch được, hãy thêm đoạn sau vào tệp wpml-config.xml của bạn:

<gutenberg-block type="foo/link" translate="1">
	<key name="label" />
	<key name="url" type="link" />
</gutenberg-block>

Trong cấu hình này, việc chỉ định type="link" cho thuộc tính url cho phép WPML tự động dịch URL.

Không gian tên của khối

Bạn có thể có cấu hình toàn cục cho không gian tên của khối.

Tên khối không còn là phần bắt buộc của định nghĩa nữa.

Nếu cấu hình khối giống nhau cho tất cả các khối trong một không gian tên, bạn có thể viết nó như thế này:

Các khối trong một không gian tên
<wpml-config>
  <gutenberg-blocks>
    <gutenberg-block type="my-plugin" translate="1">
        <key name="data">
            <key name="/^[^_]\S+$/" search-method="regex" />
        </key>
    </gutenberg-block>
  </gutenberg-blocks>
</wpml-config>

Tự động chuyển đổi ID trong các khối

Việc chuyển đổi ID rất linh hoạt và cố gắng thích ứng với hầu hết các định dạng ID có thể (ID đơn, danh sách ID, mảng được tuần tự hóa, mảng được mã hóa JSON).

Hãy xem xét khối sau:

Tự động chuyển đổi ID trong các khối – Ví dụ về khối
<!-- wp:foo/form {"ids":[27,28]} -->
<div class="wp-block-foo-form-wrap">
  <form class="foo-form" action="" method="post">
    <input type="hidden" name="foo_form_post_ids" value="27,28" />
    <input type="submit" />
  </form>
</div>
<!-- /wp:foo/form -->

Bạn có thể khai báo, dưới dạng ID bài viết, các ID thuộc tính khối và giá trị thuộc tính thẻ HTML foo_form_post_ids như bên dưới:

Các ID thuộc tính khối và giá trị thuộc tính thẻ HTML
<gutenberg-block type="foo/form" translate="0">
  <key name="ids">
      <key name="*" type="post-ids" sub-type="post" />
  </key>
  <xpath type="post-ids" sub-type="post">//*[@name="foo_form_post_ids"]/@value</xpath>
</gutenberg-block>

Khối sẽ được chuyển đổi với mức độ ưu tiên cao nhất trên bộ lọc render_block_data như bên dưới:

Khối được chuyển đổi bởi bộ lọc render_block_data
<!-- wp:foo/form {"ids":[42,43]} -->
<div class="wp-block-foo-form-wrap">
    <form class="foo-form" action="" method="post">
        <input type="hidden" name="foo_form_post_ids" value="42,43" />
        <input type="submit" />
    </form>
</div>
<!-- /wp:foo/form -→

Bạn có thể sử dụng các thuộc tính cấu hình sau:

  • type – có thể là post-ids hoặc taxonomy-ids
  • sub-type (tùy chọn): có thể là thực thể cụ thể của type nếu nó đã được biết. Ví dụ: product cho loại nội dung tùy chỉnh Product. Nếu không được xác định, thực thể cụ thể sẽ được đoán.

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 Các 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:

Được viết bởi Amir · Cập nhật lần cuối vào 5 tháng 6 năm 2025