Merge Proposal: Preferred Languages

Almost 8 years ago the Preferred Languages feature project was kicked off in response to a feature requestfeature request A feature request should generally begin the process in the ideas forum, on a mailing list, as a plugin, or brought to the attention of the core team, such as through scope meetings held for each major release. Unsolicited tickets of this variety are typically, therefore, discouraged. in #28197. Right now it is probably the oldest active feature pluginFeature Plugin A plugin that was created with the intention of eventually being proposed for inclusion in WordPress Core. See Features as Plugins.. Over time there were numerous updates, bugbug A bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority. fixes, and even a complete refactor. Preferred Languages was always built and maintained with the goal in mind to merge it into coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. one day. Now the time is finally right to do so.

Purpose & Goals

As a quick reminder, Preferred Languages replaces the existing languages dropdown with a supercharged version that lets you select multiple preferred languages. WordPress then tries to load the translations for the first language that’s available, falling back to the next language in your list otherwise. Without this, WordPress would just fall back to English (US) in such cases, which is not a great experience. Such a UIUI User interface is a pretty standard feature that can be seen for example also in operating system and browser settings.

Preferred Languages UI, showing the list of selected languages on the settings page.
Example of the Preferred Languages UI on the settings page

Note: Preferred Languages works for both the site language (can be set at Settings -> General) and the user language (can be set in the profile).

Project Background

You may wonder why it took such a long time. Since the project’s inception, a lot has changed in WordPress. For example, GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. happened. That’s why Preferred Languages saw a complete rewrite using the same ReactReact React is a JavaScript library that makes it easy to reason about, construct, and maintain stateless and stateful user interfaces. components that also power the blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. editor. With Gutenberg we also saw the introduction of JavaScript localization, which required further iterations to Preferred Languages. Then there was a need for merging incomplete translations, reducing the chances that you see missing strings in English. However, merging translations was very bad for performance, as it involves loading lots of translationtranslation The process (or result) of changing text, words, and display formatting to support another language. Also see localization, internationalization. files. In WordPress 6.5 we finally completely replaced the localization library with a more performant solution that natively supports loading multiple files at once. So this last remaining blockerblocker A bug which is so severe that it blocks a release. is now finally resolved!

Internationalization and localization is a core part of WordPress and relevant for more than half of all users. That’s why this functionality belongs natively into WordPress core and not in a (canonical) plugin. Merging Preferred Languages into core would allow the fallback logic to run much closer to where translation loading happens, reducing the risk for bugs and pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the Plugin Directory or can be cost-based plugin from a third-party incompatibilities. Plus, the UI impact is minimal, as it simply expands an existing language dropdown with additional features.

Implementation Details

The UI is built using TypeScript and React and the @wordpress/* npm packages also used for Gutenberg. This makes for a consistent look & feel and will make it easy to integrate it into any revamped WordPress adminadmin (and super admin) UI. The back end parts were developed in such a way that merging them into core eventually is as straightforward as possible, so a patchpatch A special text file that describes changes to code, by identifying the files and lines which are added, removed, and altered. It may also be referred to as a diff. A patch can be applied to a codebase for testing. can be developed relatively quickly.

Preferred Languages has been tested in production websites over numerous years by thousands of users. It works in all major browsers supported by WordPress, follows accessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). ( best practices, and gracefully falls back to the old single language dropdown if JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. is disabled.

Contributors and Feedback

While I (@swissspidy) have been the lead developer of the plugin, valuable input and contributions have come from others in the community.

This is a proposal and is subject to revision based on your feedback. If you haven’t already tried out the plugin, please download and install it from The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. or the comfort of your WordPress admin. You can review the current code and leave feedback at the project’s GitHub repository or in #core-i18n on SlackSlack Slack is a Collaborative Group Chat Platform The WordPress community has its own Slack Channel at

All feedback will be collected over the next couple of weeks. After that, the received feedback will be discussed and next steps determined. The goal is to work on and land a patch quickly to ensure that the feature gets plenty of testing in WordPress trunktrunk A directory in Subversion containing the latest development code in preparation for the next major release cycle. If you are running "trunk", then you are on the latest revision..

Props to @ocean90 for reviewing this post.

#6-6, #feature-plugins, #feature-projects, #i18n, #merge-proposals, #polyglots, #preferred-languages