translate_user_role()WP 2.8.0

Переводит название роли.

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

Вызов функции before_last_bar() нужен потому что старые установки хранят роли в старом контексте 'Role name|User role' и сохранить старый контент это проще чем менять (исправлять) его в БД.

Работает на основе: translate_with_gettext_context(), before_last_bar()

Хуков нет.

Возвращает

Строку. Переведенную роль или оригинальное название роли, если не удалось перевести.

Использование

translate_user_role( $name, $domain );
$name(строка) (обязательный)
Название роли, например "Administrator".
$domain(строка)
Идентификатор файла перевода, указывается при регистрации и подключении файла перевода. Если не указать, то будет использован дефолтный файл перевода, который используется в WordPress.
По умолчанию: 'default'

Примеры

1

#1 Убедитесь, что первая буква $name написана с заглавной буквы!

Например, в этом случае будет ошибка и вернется исходное значение $name:

translate_user_role( 'administrator' ); // administrator

Но этот вариант вернет перевод $name:

translate_user_role( 'Administrator' ); // 管理者
0

#2 Переведем все роли

Чтобы понять, зачем нужна функция 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] => Administrator
	[editor]        => Editor
	[author]        => Author
	[contributor]   => Contributor
	[subscriber]    => Subscriber

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

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

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

Попробуем перевести название ролей традиционной __()

$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] => Administrator
	[editor]        => Редактор
	[author]        => Автор
	[contributor]   => Contributor
	[subscriber]    => 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 );

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

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

Мы получили правильные переводы. Но зачем тогда нужна функция 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]             => Тестовая роль
)
*/
0

#3 Выведем роль пользователя в локализованном виде

/**
 * Returns localized user role name by ID.
 *
 * @param int $user_id User ID.
 * @return string Localized user role name.
 *
 * @since 2023-04-06
 * @version 1.0.0
 */
function get_localized_user_role_name( $user_id ) {
	$user = get_userdata( $user_id );
	$roles = [];

	foreach ( wp_roles()->roles as $role_name => $role_details ) {

		if ( $role_name === 'subscriber' ) {
			$roles[ $role_name ] = __( 'Пользователь', 'User role' );
		} else {
			$roles[ $role_name ] = _x( $role_details['name'], 'User role' );
		}
	}

	$user_role = $user->roles[0];

	return $roles[ $user_role ] ?? '';
}
  1. Функция get_localized_user_role_name возвращает локализованное название роли пользователя по его ID.
  2. При вызове функции необходимо передать ID пользователя в качестве аргумента.
  3. Если роль не найдена, функция вернет пустую строку.
  4. В функции используется цикл foreach для перебора всех ролей, доступных в системе.
  5. Если роль является 'subscriber', то ее название переводится на русский язык, используя функцию __().
  6. Для остальных ролей используется функция _x() для локализации названия.
  7. При выводе значения роли используется оператор объединения с null coalescing, чтобы избежать ошибок, если значение не определено.

Код для вывода в шаблоне:

<?php echo get_localized_user_role_name( wp_get_current_user()->ID ); ?>

Список изменений

С версии 2.8.0 Введена.
С версии 5.2.0 Added the $domain parameter.

Код translate_user_role() WP 6.4.3

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