translate_user_role() │ WP 2.8.0

To understand why the translate_user_role() function is needed, let's see how WordPress system roles are stored.

$roles = [];

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

print_r( $roles );

The contents of the variable $roles will be:

Array (
	// System roles
	[administrator] => Administrator
	[editor]        => Editor
	[author]        => Author
	[contributor]   => Contributor
	[subscriber]    => Subscriber

	// User roles
	[project_expert] => Expert
	[project_moderator] => Moderator
	[project_tracker] => Tracker
	[project_tracker_fake] => Tracker (unconfirmed)
	[project_leader] => Supervisor
	[test_role] => Test role
)

For the example, custom roles were created by plugins and the theme with add_role(), where their names in Russian were added as the second parameter. The system roles are also added (see. populate_roles_160()), but the names of the roles are passed in English, and then translated, if necessary, based on the translation files.

Most often, the WP_Roles{} class or its wrapper in the form of the wp_roles() function is used to get the list of roles and their capabilities, which returns data and does not have translated role names, except when the name was put there immediately translated, as in our example done with custom roles.

Let's try to translate the name of the roles of the traditional __()

$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 (
	// System roles
	[administrator] => Administrator
	[editor] => Editor
	[author] => Author
	[contributor]   => Contributor
	[subscriber]    => Subscriber

	// User roles
	[project_expert] => Expert
	[project_moderator] => Moderator
	[project_tracker] => Tracker
	[project_tracker_fake] => Tracker (unconfirmed)
	[project_leader] => Supervisor
	[test_role] => Test role
)
*/

Why don't some of the system roles get transferred? Because they have a context, this is what it looks like in the po file:

msgctxt "User role"
msgid "Administrator"
msgstr "Administrator"

To translate such strings correctly, you must use function _x() with context 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 (
	// System roles
	[administrator] => Administrator
	[editor] => Editor
	[author] => Author
	[contributor] => Participant
	[subscriber] => Subscriber

	// User roles
	[project_expert] => Expert
	[project_moderator] => Moderator
	[project_tracker] => Tracker
	[project_tracker_fake] => Tracker (unconfirmed)
	[project_leader] => Supervisor
	[test_role] => Test role
)
*/

We got the correct translations. But then why do we need translate_user_role()? Not only does it do the same thing as in the last example, but it also takes into account old uses of role names and substitutes the right context, thus avoiding potential errors

The final version:

$roles = [];

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

print_r( $roles );

/*
Array (
	// System roles
	[administrator] => Administrator
	[editor] => Editor
	[author] => Author
	[contributor] => Participant
	[subscriber] => Subscriber

	// User roles
	[project_expert] => Expert
	[project_moderator] => Moderator
	[project_tracker] => Tracker
	[project_tracker_fake] => Tracker (unconfirmed)
	[project_leader] => Supervisor
	[test_role] => Test role
)
*/

For example, in this case there will be an error and the original value of $name will be returned:

translate_user_role( 'administrator' ); // administrator

But this option will return a translation of $name:

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