Создание пакетов строк

Узнайте, как создавать пакеты строк для Ваших плагинов и тем оформления, чтобы помочь пользователям легко переводить контент с помощью 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 — название типа, должно совпадать с типом для пакетов.
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). Если отсутствует, это будет версия слага для «типа».
$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 );

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

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

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

$userId = 123;

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

Дополнительные ресурсы

• Файл языковой конфигурации WPML — руководство по использованию файла wpml-config.xml, который указывает, какие тексты WPML должен переводить в плагинах и темах оформления.
• Multilingual Tools — инструмент для тестирования Ваших настроек конфигурации и проверки совместимости с WPML.