如何创建字符串包

了解如何为您的插件和主题创建字符串包，以帮助用户使用 WPML 轻松翻译内容。

字符串包是在特定上下文中“捆绑”在一起的字符串组。其目的是消除单独翻译每个字符串的需求，从而帮助最终用户更高效地翻译内容。

例如，以下是用户在有和没有字符串包的情况下翻译自定义用户字段的方式：

没有字符串包

用户需要逐个翻译字符串，且没有自动翻译选项。

有字符串包

用户可以一次性翻译多个字符串，并提供自动翻译选项。

如您所见，字符串包允许用户一次翻译多个自定义用户字段，从而简化了翻译过程。为了向您的用户提供最佳的翻译体验，请按照以下步骤创建您自己的字符串包。

如果您想查看我们在以下步骤中涵盖的完整字符串包实现，请查看这个包含我们所用测试插件的 GitHub 仓库（在新标签页中打开）。

1. 确定可翻译内容

第一步是确定用户想要翻译的内容，例如标题、标签和用户生成的内容。

2. 声明包类型

接下来，您需要声明您的包类型。此步骤有助于 WPML 检测哪些字符串包连接到活动的插件，并仅翻译这些包。

作为比较，此过滤器对字符串包的作用就像 register_post_types 过滤器对文章类型的作用一样。

要声明包类型，请使用 wpml_active_string_package_kinds （在新标签页中打开）过滤器：

define( 'FOO_USER_FIELD_PACKAGE_KIND_TITLE', 'OTGS Foo User Fields' );

define( 'FOO_USER_FIELD_PACKAGE_KIND_SLUG', 'otgs-foo-user-fields' );

add_filter( 'wpml_active_string_package_kinds', function( $kinds ) {

   $kinds[ FOO_USER_FIELD_PACKAGE_KIND_SLUG ] = [

            'title'  => FOO_USER_FIELD_PACKAGE_KIND_TITLE,

            'slug'   => FOO_USER_FIELD_PACKAGE_KIND_SLUG,

            'plural' => FOO_USER_FIELD_PACKAGE_KIND_TITLE,

    ];

    return $kinds;

} );

参数定义

title – 类型的标题，应与包的 kind 相同。
plural – 标题的复数形式。
slug – 类型的别名，应与包的 kind_slug 相同。

3. 创建包并注册字符串

接下来，您需要创建一个包，并使用 wpml_register_string （在新标签页中打开）钩子注册它要分组的字符串：

$userId = 123;

$user   = get_user_by( 'id', $userId );

$package = [

    'kind'      => FOO_USER_FIELD_PACKAGE_KIND_TITLE, // The "namespace".

    'kind_slug' => FOO_USER_FIELD_PACKAGE_KIND_SLUG, // The "namespace" slug.

    'name'      => $userId, // Can be a string or an integer, but should be unique inside the "kind" namespace.

    'title'     => $user->display_name, // The title for the package entity inside the "kind" namespace.

];

$fooUserFields = get_option( 'otgs_foo_user_fields' );

foreach ( $fooUserFields as $fooUserField ) {

$fieldValue = get_user_meta( $userId, $fooUserField, true );

do_action( 'wpml_register_string', $fieldValue, sanitize_key( $fooUserField ), $package, $fooUserField, 'LINE' );

}

参数定义

$kind – 实体的命名空间标签（例如，Gravity Form）。
$kind_slug – 实体的命名空间别名（例如，gravity-form）。如果缺失，它将是“kind”的别名版本。
$name – 实体在类型内的唯一标识符，可以是字符串（例如，别名）或整数（例如，ID）。
$title – 实体在类型内的标题。建议使用真实实体的标题。

虽然不是必须的，但您也可以包含两个额外的参数：
$edit_link – 编辑对象的 URL。
$view_link – 查看对象的 URL。

4. 检索翻译

最后，要在前端显示翻译，您需要使用 wpml_translate_string （在新标签页中打开）钩子：

$userId = 123;

$user   = get_user_by( 'id', $userId );

$package = [

        'kind'      => FOO_USER_FIELD_PACKAGE_KIND_TITLE, // The "namespace".

        'kind_slug' => FOO_USER_FIELD_PACKAGE_KIND_SLUG, // The "namespace" slug.

        'name'      => $userId, // Can be a string or an integer, but should be unique inside the "kind" namespace.

        'title'     => $user->display_name, // The title for the package entity inside the "kind" namespace.

];

$fooUserFields = get_option( 'otgs_foo_user_fields' );

$translatedFieldValues = [];

foreach ( $fooUserFields as $fooUserField ) {

    $fieldValue              = get_user_meta( $userId, $fooUserField, true );

    $translatedFieldValues[ $fooUserField ] = apply_filters( 'wpml_translate_string', $fieldValue, sanitize_key( $fooUserField ), $package );

}

更新和删除字符串

每当用户更新内容时，WPML 都需要能够识别新字符串以及被删除的字符串。要将这些更改通知 WPML，请使用两个函数包装您的注册代码：

$userId = 123;

$package = [

        'kind'      => FOO_USER_FIELD_PACKAGE_KIND_TITLE, // The "namespace".

        'kind_slug' => FOO_USER_FIELD_PACKAGE_KIND_SLUG, // The "namespace" slug.

        'name'      => $userId, // Can be a string or an integer, but should be unique inside the "kind" namespace.

        // The 'title' key is not not required in the "translate" context.

];

do_action( 'wpml_start_string_package_registration', $package );

$fooUserFields = get_option( 'otgs_foo_user_fields' );

foreach ( $fooUserFields as $fooUserField ) {

    $fieldValue = get_user_meta( $userId, $fooUserField, true );

    do_action( 'wpml_register_string', $fieldValue, sanitize_key( $fooUserField ), $package, $fooUserField, 'LINE' );

}

do_action( 'wpml_delete_unused_package_strings',$package );

删除字符串包

当用户删除内容时，您还应该删除其关联的字符串包。这包括所有相关的字符串、翻译和任务。通过执行此清理操作，您可以确保网站保持高效，而不会有任何残留数据使数据库变得混乱。

要删除字符串包，请挂钩到插件或主题中的适当操作，并调用 wpml_delete_package （在新标签页中打开）函数：

$userId = 123;

do_action( 'wpml_delete_package', $userId, FOO_USER_FIELD_PACKAGE_KIND_SLUG );

其他资源

WPML 语言配置文件 – 关于使用 wpml-config.xml 的指南，该文件指示 WPML 在插件和主题中应翻译哪些文本。
Multilingual Tools – 用于测试您的配置设置并确认与 WPML 兼容性的工具。