User Admin Languages and Locale Switching in 4.7

In WordPress 4.7 users will be able to select their preferred locale (language) when editing their profile. 🎉🎉 This allows for greater personalization of the WordPress admin and therefore a better user experience.

The back end will be displayed in the user’s individual locale while the locale used on the front end equals the one set for the whole site. If the user didn’t specify a locale, the site’s locale will be used as a fallback. The new locale property of the WP_User class can be used to retrieve the user’s locale setting.

The new user language option when editing the profile

The new user language option

To enable sending emails in the language of the recipient and not the current user’s language, an API has been introduced to switch locales and translations at any point during the page load.

Here are some of the new API functions with usage examples.

get_user_locale( $user_id )

This function is used to retrieve the locale of any user. When no user ID is set it uses the current user. The user locale should be used for any user-facing screens in the admin.

The user locale is stored as a user meta locale. Therefore it can be modified with the get_{$meta_type}_metadata filter.
If the meta field is empty the value of get_locale() is returned.

switch_to_locale( $locale )

switch_to_locale() switches the locale and (un)loads text domains according to a given locale. This includes the global $wp_locale object as well. It can be used together with get_locale() or get_user_locale(). Core’s main purpose of this function is to be able to send emails like password/email change notifications in the recipient’s language. Admin emails, emails for  get_option( 'admin_email' ), are using get_locale(), the site language.

When switching a locale several actions are fired which allows one to perform further actions:

  • change_locale: Fires when a locale is switched or restored. Core uses it to re-init post types and taxonomies.
  • switch_locale: Fires when a locale is switched.
  • restore_previous_locale: Fires when a locale is restored to the previous one.

restore_previous_locale() and restore_current_locale()

restore_previous_locale() can be used to restore the previous locale. Example:

$locale_switched = switch_to_locale( get_user_locale() );

// Do something.

if ( $locale_switched ) {
    restore_previous_locale();
}

Use restore_current_locale() if you want to empty the current stack and restore the original locale.

is_locale_switched()

As the name implies, it checks whether switch_to_locale() is in effect.

WP_Locale_Switcher

switch_to_locale(), restore_previous_locale(), restore_current_locale(), and is_locale_switched() are wrapping the same named methods of a new WP_Locale_Switcher class. This class is responsible for holding a stack of locales and filtering the actual locale through the locale filter.

Note about admin-ajax.php

As admin-ajax.php is in the admin, anyone getting translated strings via Ajax will get strings in the user’s locale when they are logged in. You can use switch_to_locale( get_locale() ) to ensure the string is returned in the site’s locale, rather then the user’s locale. Or, ideally, leverage the REST API. 💪🏼

For background information on these changes see #29783, #26511, and #38485.

Related dev note: Changed loading order for current user in 4.7.

#4-7, #dev-notes, #i18n