JavaScript Internationalization

Prequel

Over the last few releases, WordPress has made huge steps in prioritizing internationalization and localization throughout around core. To name a few highlights: language packs for core, language packs for plugins and themes, a language chooser, just-in-time loading for translations, and a user-specific language setting. But core isn’t the only place improvements have been made.

translate.wordpress.org is the platform for making WordPress available in as many languages as possible. Did you know that WordPress 4.6 is currently translated into 72 – s e v e n t y t w o – languages? Recently the number of unique translators passed the 10k mark. 🌎🌍🌏

The platform is powered by GlotPress, a collaborative, web-based software translation tool.

Internationalization is not a feature, it fixes a usability issue for many users whose primary language is not English. And that’s about 47% of our users.

The next big thing

As of today, WordPress doesn’t support a proper internationalization API in JavaScript. There are two, 4-year old tickets, #22229 and #20491, which request such an API. (The former one was closed as a duplicate of #20491 since an internationalization API in JavaScript should provide support for plurals by default.)

And that’s what this post is about: JavaScript Internationalization.

@swissspidy and I (@ocean90) have been thinking about and working on this topic, and now is the time to gather feedback on the direction and get help from everyone interested.

As you may have noticed in the prequel, internationalization spans more than WordPress core. We’ve split the task into four areas: Core, GlotPress, wp-i18n-tools, and language packs.

Jed and wp.i18n (Core)

Since we didn’t want to reinvent any wheels, our proposal is to use Jed as the base library. Jed provides “Gettext Style i18n for Modern JavaScript Apps”.

wp.i18n will be a wrapper for Jed and should be used by WordPress and plugins/themes. One of the biggest benefits of leveraging Jed is that the actual implementation is very similar to the one we already have for PHP code. The latest patch currently introduces these API functions:

  • wp.i18n.getLocale()
  • wp.i18n.loadLocaleData( data )
  • wp.i18n.addTranslations( domain, data )
  • wp.i18n.__( text, domain )
  • wp.i18n._x( text, context, domain )
  • wp.i18n._n( single, plural, number, domain )
  • wp.i18n._nx( single, plural, number, context, domain )
  • wp.i18n.esc_attr__( text, domain )
  • wp.i18n.esc_html__( text, domain )
  • wp.i18n.esc_attr_x( text, context, domain )
  • wp.i18n.esc_html_x( text, context, domain )
  • wp.i18n.numberFormat( number, decimals )
To do
  • Rethink WP_Scripts::load_translation_file() and get_js_i18n_data(), add tests.
  • Get feedback on the proposed API. (That’s this post!)
  • Apply the new API in our JS files.
    • There’s a POC patch that can be worked upon.
    • Do not forget: Underscore templates.
  • Include date of json files in update requests for language packs.
    • See wp_get_installed_translations().
    • See wp_get_json_file_data(), maybe json_decode() might be enough for this case.
    • What’s the format for meta data? See this GitHub issue for discussion.
  • sprintf() in JavaScript – useful for core?

GlotPress (translate.wordpress.org)

Jed supports JSON for translation files. GlotPress currently doesn’t support exporting translations in a JSON format. But there is a pull request which adds the required functionality to GlotPress. The format is going to support “simple” JSON (key -> value) and a Jed 1.x compatible format. The latter will be used by wp.i18n.

To do
  • Get the PR merged. Done. πŸŽ‰
  • Find a solution for the missing meta data, see the GitHub issue mentioned before.
  • To enable exports like “get all translations for file common.js”, the current filter system in GlotPress needs to be improved to support search only in file references and search for multiple file references.

wp-i18n-tools (Meta)

A script named MakePOT parses PHP files to extract the original strings and their file references. This script needs to be extended to also parse JavaScript files. A POC has been created.

To do
  • Convert the POC into nice code with tests.
  • Fix #20881 because it’s important for the GlotPress export that all file references remain.

Language Packs (Meta)

Currently a language pack includes a .po and a .mo file. Support needs to be added so that a .json file gets bundled if a project has translations for JavaScript files.

To do
  • Export Jed files when JS translations exist.
  • Include JSON file in language packs.
  • Update API to support version checks for JSON files.

Feedback

Thanks for reading, now it’s your turn. πŸ™‚ Do you have any feedback? Are there things we should do differently? Do you have resources to help us? Please let us know in the comments!

There are currently no meetings scheduled but we’re happy to discuss any topics in #core-i18n. Just say “Hi”!