User Admin Languages and Locale Switching in 4.7

In WordPress 4.7 users will be able to select their preferred localeLocale A locale is a combination of language and regional dialect. Usually locales correspond to countries, as is the case with Portuguese (Portugal) and Portuguese (Brazil). Other examples of locales include Canadian English and U.S. English. (language) when editing their profile. 🎉🎉 This allows for greater personalization of the WordPress adminadmin (and super 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 sitesite (versus network, blog). 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 APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. 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 metaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. locale. Therefore it can be modified with the get_{$meta_type}_metadata filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output..
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(). CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.’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 APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/.. 💪🏼

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

Related dev notedev note Each important change in WordPress Core is documented in a developers note, (usually called dev note). Good dev notes generally include: a description of the change; the decision that led to this change a description of how developers are supposed to work with that change. Dev notes are published on Make/Core blog during the beta phase of WordPress release cycle. Publishing dev notes is particularly important when plugin/theme authors and WordPress developers need to be aware of those changes.In general, all dev notes are compiled into a Field Guide at the beginning of the release candidate phase.: Changed loading order for current user in 4.7.

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