Как создавать пакеты строк

Узнайте, как создавать пакеты строк для Ваших плагинов и тем, чтобы помочь пользователям легко переводить контент с помощью WPML.

Пакеты строк — это группы строк, «связанные» вместе в определенном контексте. Их цель — помочь конечным пользователям переводить контент более эффективно, устраняя необходимость переводить каждую строку по отдельности.

Например, вот как пользователи переводили бы произвольные поля, с пакетом строк и без него:

Как видите, пакеты строк упрощают процесс перевода, позволяя пользователям переводить несколько произвольных полей за один раз. Чтобы обеспечить Вашим пользователям наилучший опыт перевода, выполните следующие шаги для создания собственных пакетов строк.

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 об этих изменениях, оберните Ваш код регистрации двумя функциями:

• wpml_start_string_package_registration (открывается в новой вкладке)
• wpml_delete_unused_package_strings (открывается в новой вкладке)

$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 );

Удаление пакетов строк

Когда пользователи удаляют контент, Вам также следует удалить связанный с ним пакет строк. Это включает в себя все связанные строки, переводы и задания на перевод. Выполняя такую очистку, Вы гарантируете, что сайт останется производительным, без остаточных данных, засоряющих базу данных.

Чтобы удалить пакет строк, подключитесь к соответствующему хуку (action) в Вашем плагине или теме и вызовите функцию 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.