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

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

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

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

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

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

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

自定义小工具也指由外部开发者专门为 Elementor 等页面构建器开发的附加组件插件中的任何小工具。

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

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

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

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

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

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

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

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

为了能够在 wpml-config.xml 文件中注册自定义小工具，您首先需要找到有关它的一些基本信息。

您可以使用 JSM Show Post Metadata 等插件轻松获取此信息。该插件在文章编辑页面底部的元数据框中显示文章元数据及其未序列化的值。

或者，您可以使用以下步骤获取此信息：

1. 前往 WPML → 设置页面，向下滚动到自定义字段翻译部分，然后单击显示系统字段链接。
2. 将 _elementor_data 自定义字段设置为翻译。
3. 创建一个新页面，仅添加您希望注册的 Elementor 小工具。保存页面。
4. 前往 WPML → 设置，在翻译编辑器部分临时激活经典翻译编辑器选项。
5. 尝试使用经典翻译编辑器翻译您在第 3 步中创建的页面，您会注意到一个序列化数组，如下所示：

6. 复制序列化数组的内容。
7. 使用您首选的反序列化工具更好地查看小工具如何输出其内容。在我们的例子中，我们使用了 Unserialize 网站。

以下是您将看到的数组内容的解释：

• [widgetType] 包含插入到小工具标签 name 属性中的名称。
• 实际字段将位于数组（Array）内，您可以通过搜索 [0] 来找到它们，这将调出数组第一个元素的内容。
• field 值将是包含字段名称的括号内的名称。例如：[title] => this is a field title。在这种情况下，“title”是您需要的文本。
• “Items of”将从创建数组的元素中获取其值。例如：[contents]=> array。在这种情况下，“contents”是您需要的文本。

获得此信息后，您就可以继续实际注册小工具以进行翻译了。

注册简单小工具

以下视频将带您了解注册简单 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）下，您添加一个键等于小工具名称的条件。当小工具名称与数据中的小工具键不同时可以使用它，但通常不需要。

3. 添加小工具的字段，将它们包裹在 <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 小工具的以下数据结构为例：

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

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

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

请注意，小工具可以同时具有这两种类型：字段和项目内字段。请查看这个同时使用两者的示例：

<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: 标签前缀。该前缀也会出现在高级翻译编辑器中，从而更易于识别和翻译每个字段：

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

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

其他资源

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

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

• 注册页面构建器内容以进行翻译
• 使用 WPML 翻译自定义简码
• 使用 WPML 配置文件设置自定义字段的翻译选项
• 将自定义术语、类型和分类法注册为可翻译
• 使自定义 Gutenberg 区块可翻译
• 翻译主题和插件保存在 wp_options 中的文本
• 使用 WPML 配置文件自定义 WPML 语言切换器