Функция TRANSLATE_USER_ROLE() в WordPress: перевод имени роли пользователя

## Функция TRANSLATE_USER_ROLE() │ WP 2.8.0

Функция переводит имя роли пользователя.

Имена ролей хранятся в базе данных, а не в исходном коде, поэтому есть специальные вызовы функции gettext, которые добавляют их в файл POT. Эта функция корректно переводит их обратно.

### Зачем нужен вызов before_last_bar()

Вызов функции before_last_bar() необходим, потому что в старых установках роли хранятся в старом формате: 'Имя роли|Роль пользователя'. Пропустить часть после последней черты проще, чем исправлять данные в БД. Новые установки этой проблемы не имеют.

**Использует:** translate_with_gettext_context(), before_last_bar()

**Хуки:** Нет.

### Возвращаемое значение

Строка. Переведённое имя роли в случае успеха, оригинальное имя в случае ошибки.

### Пример использования

```php
translate_user_role( $name, $domain );

• $name (строка) (обязательный) — Имя роли.
• $domain (строка) — Текстовый домен. Уникальный идентификатор для получения переведённых строк. По умолчанию: 'default'.

Примеры

Пример 1: Перевод всех ролей

Чтобы понять, зачем нужна функция translate_user_role(), давайте посмотрим, как хранятся системные роли в WordPress.

$roles = [];

foreach ( wp_roles()->roles as $role_name => $role_details ) {
    $roles[ $role_name ] = $role_details['name'];
}

print_r( $roles );

Содержимое переменной $roles будет следующим:

Array (
    // Системные роли
    [administrator] => Администратор
    [editor]        => Редактор
    [author]        => Автор
    [contributor]   => Участник
    [subscriber]    => Подписчик

    // Пользовательские роли
    [project_expert] => Эксперт
    [project_moderator] => Модератор
    [project_tracker] => Отслеживатель
    [project_tracker_fake] => Отслеживатель (неподтверждённый)
    [project_leader] => Руководитель
    [test_role] => Тестовая роль
)

В примере пользовательские роли были созданы плагинами и темой с помощью функции add_role(), где их имена на русском языке были добавлены как второй параметр. Системные роли также добавляются (см. populate_roles_160()), но имена ролей передаются на английском и затем переводятся, если это необходимо, на основе файлов перевода.

Чаще всего, для получения списка ролей и их возможностей используется класс WP_Roles или его обертка в виде функции wp_roles(), которая возвращает данные без переведённых имён ролей, кроме тех случаев, когда имя было сразу передано в переведённом виде, как в нашем примере с пользовательскими ролями.

Пример 2: Перевод с использованием функции __()

Попробуем перевести имена ролей с помощью традиционной функции __():

$roles = [];

foreach ( wp_roles()->roles as $role_name => $role_details ) {
    //$roles[ $role_name ] = translate_user_role( $role_details['name'] );
    $roles[ $role_name ] = __( $role_details['name'] );
}

print_r( $roles );

Результат будет следующим:

Array (
    // Системные роли
    [administrator] => Администратор
    [editor] => Редактор
    [author] => Автор
    [contributor]   => Участник
    [subscriber]    => Подписчик

    // Пользовательские роли
    [project_expert] => Эксперт
    [project_moderator] => Модератор
    [project_tracker] => Отслеживатель
    [project_tracker_fake] => Отслеживатель (неподтверждённый)
    [project_leader] => Руководитель
    [test_role] => Тестовая роль
)

Почему некоторые системные роли не переводятся? Это связано с контекстом, который выглядит так в .po файле:

msgctxt "User role"
msgid "Administrator"
msgstr "Администратор"

Чтобы перевести такие строки правильно, необходимо использовать функцию _x() с контекстом "User role":

$roles = [];

foreach ( wp_roles()->roles as $role_name => $role_details ) {
    $roles[ $role_name ] = _x( $role_details['name'], 'User role' );
}

print_r( $roles );

Мы получили правильные переводы. Но зачем нам нужна функция translate_user_role()? Она делает то же самое, что и последний пример, но также учитывает старые способы использования имён ролей и подставляет правильный контекст, избегая потенциальных ошибок.

Заключительная версия

$roles = [];

foreach ( wp_roles()->roles as $role_name => $role_details ) {
    $roles[ $role_name ] = translate_user_role( $role_details['name'] );
}

print_r( $roles );

Результат:

Array (
    // Системные роли
    [administrator] => Администратор
    [editor] => Редактор
    [author] => Автор
    [contributor] => Участник
    [subscriber] => Подписчик

    // Пользовательские роли
    [project_expert] => Эксперт
    [project_moderator] => Модератор
    [project_tracker] => Отслеживатель
    [project_tracker_fake] => О��слеживатель (неподтверждённый)
    [project_leader] => Руководитель
    [test_role] => Тестовая роль
)

Пример 3: Убедитесь, что первая буква в $name заглавная!

Если использовать слово с маленькой буквы, то вернётся оригинальное значение $name:

translate_user_role( 'administrator' ); // administrator

А вот использование заглавной буквы вернёт перевод:

translate_user_role( 'Administrator' ); // Администратор

Изменения

• В версии 2.8.0 функция была введена.
• В версии 5.2.0 был добавлен параметр $domain.

Код функции TRANSLATE_USER_ROLE()

Функция хранится в wp-includes/l10n.php:

function translate_user_role( $name, $domain = 'default' ) {
    return translate_with_gettext_context( before_last_bar( $name ), 'User role', $domain );
}

Этот текст переведен и адаптирован для более простого понимания, с добавлением пояснений по коду и структуре.