WPML

注册自定义页面构建器小工具以进行翻译

更新时间：2026年4月24日

要注册自定义页面构建器小工具以进行翻译，您需要使用 wpml-config.xml 文件。请按照本教程了解如何使用它。

本指南适用于构建主题和插件，或向网站添加自定义页面构建器代码的开发者。

如果您使用第三方页面构建器，并且无法翻译网站上的自定义小工具，请联系 WPML 支持。

像 Elementor、Beaver Builder、SiteOrigin 和 Cornerstone 这样的页面构建器都自带一套小工具。这些默认小工具可以与 WPML 无缝配合使用。

有时，您可能会创建旨在与这些或其他页面构建器配合使用的自定义小工具。

自定义小工具是指任何未随页面构建器捆绑提供的独特附加小工具。这些小工具可以由您的开发团队、第三方开发者创建，或来自其他插件和主题。

自定义小工具也包括任何来自外部开发者专门为页面构建器（如 Elementor）开发的附加组件插件的小工具。

何时需要注册自定义小工具以进行翻译？

在以下情况下，您需要注册自定义小工具以进行翻译：

  • 如果它是非页面构建器最初提供的小工具
  • 如果您通过其他插件或主题创建并添加了它
  • 如果它是您的团队或第三方为您的 WordPress 网站或特定页面构建器开发的

过去，注册自定义小工具以进行翻译的最常见方法是使用自定义 PHP 代码。现在，您可以使用 WPML 的配置文件 wpml-config.xml 轻松注册小工具以进行翻译。

在 WPML 4.9 及更高版本中注册自定义 Elementor 小工具以进行翻译

在 WPML 4.9 及更新版本中，WPML 会自动识别自定义 Elementor 小工具并使其可翻译。但是，它可能会注册您不想翻译的字符串。

因此，我们强烈建议您仍然按照本页所述手动配置 wpml-config.xml 文件。这能让您控制哪些字段可翻译。

如何使用 Multilingual Tools 插件注册自定义 Elementor 小工具和 Gutenberg 区块以进行翻译

我们的 Multilingual Tools 插件包含一个适用于 Elementor 和 Gutenberg 区块的 WPML – Config Generator（WPML – 配置生成器）。此功能允许您将任何想要注册以进行翻译的自定义 Elementor 小工具或 Gutenberg 区块添加到页面中。然后，它会自动生成您所需的第一版 XML 代码。

了解如何注册自定义 Elementor 小工具以进行翻译以及如何使 Gutenberg 区块可翻译。

如何查找小工具的注册信息

为了能够在 wpml-config.xml 文件中注册自定义小工具，您首先需要找到关于它的一些基本信息：小工具的类型名称以及您想要翻译的字段名称。

将该小工具单独添加到一个新页面并保存页面。Elementor 会将页面的小工具存储在 _elementor_data 文章元数据字段中，像 JSM Show Post Metadata 这样的插件会在页面编辑器底部的元数据框中显示该字段，因此您可以在那里读取小工具的数据。

在这些数据中：

  • widgetType 是要在小工具的 name 属性中使用的名称。
  • settings 下的键是小工具的字段。包含您想要翻译的文本的键（例如 title）就是要注册的字段名称。
  • 中继器字段包含一个行数组。包含该数组的键（例如 contents）就是“items of”的名称。
在经典编辑器中复制小工具数据
在 WPML 的经典翻译编辑器中暴露的 Elementor 小工具序列化数组

掌握这些信息后，您就可以继续实际注册小工具以进行翻译了。

要检查您的工作，请在翻译编辑器中打开一个使用该小工具的页面。您注册的字段会按名称显示在那里，旁边是小工具的文本。未注册的小工具不会对翻译任务产生任何作用，因此如果没有显示其任何文本，则说明注册未生效。

注册简单小工具

以下视频将带您了解注册简单 Elementor 小工具的示例：

以下示例说明了如何注册简单小工具。这里的简单小工具是指没有中继器字段的小工具。

<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>

让我们来看看给定示例的结构：

  1. 从 <elementor-widgets> 标签开始。这告诉 WPML 您要注册哪些页面构建器小工具。它可以是以下之一：
    • <elementor-widgets>：如果您使用的是 Elementor、Elementor PRO 或任何其他 Elementor 附加组件，则必须使用此标签。
    • <beaver-builder-widgets>：如果您使用的是 Beaver Builder Lite、高级 Beaver Builder 或任何其他 Beaver Builder 附加组件，则必须使用此标签。
    • <siteorigin-widgets>：如果您使用的是 SiteOrigin 页面构建器，则必须使用此标签。
    • <cornerstone-widgets>：如果您使用的是 X 主题或 PRO 主题自带的 Cornerstone 页面构建器，则必须使用此标签。
  2. 添加您的小工具：
    • <widget name="widget_name">，其中 widget_name 是在页面构建器中用于注册小工具的名称。
    • <conditions>（可选）：在 conditions 下，您添加一个键等于小工具名称的条件。当小工具名称与数据中的小工具键不同时可以使用它，但这通常不需要。
  1. 添加小工具的字段，将它们包裹在 <fields> 标签中：
    • field: 字段的 id。这与通过 Control_stack::add_control 函数添加控件时使用的 id 相同。
    • type（可选）：字段的类型。这是在 WPML 高级翻译编辑器或经典翻译编辑器中显示的文本，以帮助译者了解正在翻译哪个字段。
    • editor_type（可选）：这是在 WPML 经典翻译编辑器中使用的文本字段类型。有效值为 LINE、AREA、LINK 和 VISUAL。如果缺失，默认值为 LINE。
    • key_of（可选）：这仅用于在 <fields-in-item> 标签内包含数组的 <field> 标签。

您可以使用这些元素来注册带有任意数量字段的简单小工具。

注册带有文章或分类法 ID 的字段

在上一节中，您了解到 type 属性通常用于在翻译编辑器中显示描述性文本。

但是，当您的小工具字段存储文章 ID 或分类法 ID（例如所选图像、相关文章或所选类别）时，您需要使用触发自动转换的特殊值：

  • type="post-ids" – 用于包含文章 ID 的字段
  • type="term-ids" – 用于包含分类法/术语 ID 的字段

当您使用这些 types 值时：

  • 该字段不会出现在翻译编辑器中
  • WPML 会自动转换 ID 以指向相应的已翻译内容
  • 支持单个 ID 和以逗号分隔的 ID 列表

示例：

<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>

在此示例中，可选的 sub-type 属性指定了要转换的确切文章类型或分类法：

  • 对于 type="post-ids"：使用 sub-type="attachment"、sub-type="post"、sub-type="page" 或您的自定义文章类型别名
  • 对于 type="term-ids"：使用 sub-type="category"、sub-type="post_tag" 或您的自定义分类法别名

添加 sub-type 可以避免额外的数据库查询来确定内容类型，从而提高性能。

有关更多示例，请参阅 Elementor 的配置文件并搜索 post-ids。

注册带有中继器字段的小工具

以下视频将带您了解注册带有中继器字段的高级 Elementor 小工具的示例：

对于具有中继器字段的小工具，您需要将字段包裹在 <fields-in-item items_of="tabs"> 标签中（其中 tabs 是包含重复字段的小工具名称）。请查看以下示例：

<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>

在某些情况下，小工具可以有多个中继器字段。以 Ultimate Addons for Elementor 的 Table 小工具的以下数据结构为例：

Ultimate Addons for Elementor 的 Table 小工具的数据结构

要注册此小工具，请参阅以下示例：

<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>

注册同时带有简单字段和中继器字段的小工具

请注意，小工具可以同时具有这两种类型：fields 和 fields-in-item。请查看这个同时使用两者的示例：

<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>

对字段进行分组以便更好地组织

为了提高 XML 配置的清晰度和组织性，您可以在字段标签前加上组名作为前缀。以热点小工具的这个示例为例：

<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>

在这里，热点小工具内的每个字段都以 Hotspot: 标签作为前缀。该前缀也会出现在高级翻译编辑器中：小工具的字段位于 Hotspot 框中，每个字段都带有自己的标签，从而更容易识别和翻译每个字段：

高级翻译编辑器中的热点小工具字段
高级翻译编辑器中的热点小工具字段

注册其他类型的页面构建器内容

有关注册字符串、简码等内容的更多信息，请参阅我们关于在语言配置文件中注册页面构建器内容的文档。

其他资源

要了解有关 wpml-config.xml 文件的更多信息，请访问语言配置文件指南。

有关使用 wpml-config.xml 文件自定义其他元素的信息，请访问我们的其他指南：

作者：Amir