5.0: JavaScript language packs are here 🎉

News from the JS package inclusion focus: JavaScript language packs are here! Thanks to AWESOME work by @herregroen, @ocean90, @swissspidy, @nerrad, @atimmer and @schlessera we can now translate strings in JavaScript files and distribute them via https://translate.wordpress.org. This functionality will soon be expanded to also work for plugins and themes. This is a major milestone for JavaScript development in WordPress and completes the JavaScript package inclusion focus.

How does it work?

In short, to make it work, you need to

  • use the @wordpress/i18n package for making strings in your JavaScript translatable.
  • let WordPress know that a script has translations by calling wp_set_script_translations( 'my-handle', 'my-domain' ) after you register a script.

Read more about it in the JS i18n devnote.

Can I have a look at the tickets involved?

Sure thing! Here’s an overview of all the work we’ve done in the last few weeks to get to this point:

  1. WP-CLI: Make sure wp i18n CLI command includes JavaScript translations when generating Potfiles. Relevant PRs: https://github.com/wp-cli/i18n-command/pulls?q=is%3Apr+is%3Aclosed+author%3Aherregroen
  2. Meta: generate translations on translate.wordpress.org for core, themes and plugins. Ticket: https://meta.trac.wordpress.org/ticket/3748
  3. Meta: generate and serve JS language packs from translate.wordpress.org for core, themes and plugins. Ticket: https://meta.trac.wordpress.org/ticket/3876
  4. Core: Logic to load JS translations. Ticket: https://core.trac.wordpress.org/ticket/45103
  5. Core: API to register JS translations for a script. https://core.trac.wordpress.org/ticket/45161

What’s next?

With JS language packs we have concluded the package inclusion focus. In the remaining time we will keep focus on two things:

  • Keep the packages up-to-date until 5.0 ships.
  • @herregroen will shift focus towards generating the core JS code documentation on Devhub (https://developer.wordpress.org) and making it searchable. Since this pretty much only involves meta, this is not a release blocker. But with the heaps of JavaScript that 5.0 adds to WordPress, it would be nice to have its documentation searchable and discoverable through Devhub. At the same time it would also make WordPress’ legacy JavaScript (of which a lot was documented in the last years in the JS documentation initiative) more accessible to the broader community. Work on this had already started as part of the JS docs initiative.

#i18n

New! JavaScript i18n support in WordPress 5.0

For years, internationalization (i18n) has been a thing that has been pretty well supported in WordPress when it comes to PHP development. For PHP, WordPress already provides all the tools necessary to make it as easy as possible to localize WordPress core, themes and plugins to any language. Today we are bringing the same capabilities to JavaScript development for WordPress.

How does it work?

When registering your scripts you can add wp-i18n as a dependency to allow you to add translatable strings as you would in PHP:

wp_register_script( 'my-handle', plugins_url( '/js/my-file.js', MY_PLUGIN ), array( 'wp-i18n' ) );

Inside your scripts you will then be able to use wp-18n as follows:

const { __, _x, _n, _nx } = wp.i18n;

__( '__', 'my-domain' );
_x( '_x', '_x_context', 'my-domain' );
_n( '_n_single', '_n_plural', number, 'my-domain' );
_nx( '_nx_single', '_nx_plural', number, '_nx_context', 'my-domain' );

These functions mirror their PHP counterparts and can be used in exactly the same manner.

The final step is to tell WordPress your script contains translations and of which domain, this is to allow WordPress to selectively load only the necessary translations to ensure everything is as fast as can be:

wp_set_script_translations( 'my-handle', 'my-domain' );

Advanced usage

Right now it’s already possible to ship your own translations using the load_textdomain function and passing your own MO file. This is also possible using wp_set_script_translations which accepts an optional third path argument that allows you to tell WordPress to first look elsewhere for translations:

wp_set_script_translations( 'my-handle', 'my-domain', plugins_url( '/languages', MY_PLUGIN ) );

If passed WordPress will first check if a file in the format of ${domain}-${locale}-${handle}.json exists in the given path and use it as the source of translations if so. Alternatively it will also first check the given path for the md5 filename before defaulting to the WordPress languages directory.

If you want to ship your own translation files these should be in the JED 1.x ( .json ) format. GlotPress is able to create these along with other tools such as po2json. Ideally these files should only contain translations that occur within their respective JS files.

Behind the screens

When you upload your plugin or theme to wordpress.org all JS files will automatically be parsed the same as is already being done for PHP files. Any detected translations will be added to translate.wordpress.org to allow the community to cooperate to ensure WordPress, plugins and themes are available in as many languages as possible.

In order to parse all JS files the i18n-command for wp-cli is used. This replaces makepot.php to not only allow picking up translations in JS files but also to audit strings, parse strings only of a specific text domain and even pick up a few strings that weren’t detected by makepot.php. This command is freely available and open-source as makepot.php was and it’s recommended that anyone using makepot.php transition over to this much improved replacement.

Based on these parsed translations Language Packs are generated. Traditionally these used to only contain PO and MO files, one pair for each locale. In order to selectively load only the necessary translations regardless of whether it’s used or not a few more files are being added, one JSON file for every JS file that contains translations per locale.

When parsing JS files for translations we don’t know which handle is used to register that file so we’ve had to use an alternate mechanism to find the translations belonging to each file. To do this we’re using the md5 of the relative path of each file. This is appended to the usual name of ${domain}-${locale} in the form of ${domain}-${locale}-${md5}.json.

When you set script translations for a handle WordPress will automatically figure out the relative md5 hash of your source file, check to see if a translations file exists and if so ensure that it’s loaded into wp.i18n before your script runs.

Plugin and theme support

Translation and Language packs support for plugins and themes that are hosted on the repo is expected in the upcoming weeks. The patches are ready and waiting for commit. Plugin and theme authors are encouraged to start using wp-i18n in their JavaScript projects.

Credits

This API wouldn’t have been possible without the long standing efforts of @ocean90, @swissspidy, @nerrad, @atimmer, @schlessera and more recently @herregroen. Thanks a ton for the incredible work you’ve all put into making this a reality! Another thanks to @herregroen for providing the necessary input for this devnote.

#i18n

Dev Chat Summary: November 7th (5.0 Week 6)

This post summarizes the dev chat meeting from November 7th (agenda, Slack archive). Note that the timing for this meeting will move to 2100 UTC starting Nov 14.

5.0 Planning and Updates

  • We have a lot of PRs that need review, so please pick up one or two if that’s something you excel at.
  • Beta 3 came out on Monday. Notable updates were also published about Classic Editor plugin support and meta box compatibility.
  • Patches have been issued for Gutenberg 4.0 through 3.6 so that they automatically disable the plugin early enough in the 5.0 upgrade process.
  • For the upgrade process, core will focus on messaging introducing the new editor on the post-upgrade page (aka the About page), while the Classic Editor plugin will be responsible for any communication encouraging users to give the new editor a try.
  • From the REST API desk, we are in need of some eyes/contributions on both https://github.com/WordPress/gutenberg/issues/11280 and https://github.com/WordPress/gutenberg/issues/9151
  • From the JS desk, focus has shifted to generating the core JS code documentation on developer.wordpress.org and making it searchable. Also, the JS language packs are almost here!
  • Feature freeze on Twenty Nineteen has started, which puts all focus on these bug fixes and issues.
  • There are a number of PHP related issues on the milestone for contributors who don’t feel comfortable with React. For anyone able to test, review, or work on core PHP issues, check this report: https://core.trac.wordpress.org/report/6
  • We still have a few more bug scrubs coming up this week, and could use some contributors there. A new set will be posted soon, too.

Component and Focus Updates

  • Core PHP is continuing work on Servehappy, and WSOD protection. https://make.wordpress.org/core/2018/11/05/php-meeting-recap-october-29th/
  • Core Javascript meeting covered a lot of ground (Node LTS 10.13.0, back compat, e2e tests, ). Recap is available here: https://make.wordpress.org/core/2018/11/07/javascript-chat-summary-november-6th/

Announcements and Open Floor

Next meeting

The next meeting will take place on Wednesday, November 14 21:00 UTC in the #core Slack channel. Please feel free to drop in with any updates or questions. If you have items to discuss but cannot make the meeting, please leave a comment on the upcoming agenda post so that we can take them into account.

#5-0#a11y#core#core-editor#core-js#core-media#core-php#core-restapi#dev-chat#gutenberg#summary#team-reps

JavaScript Chat Summary – November 6th

Below is a summary of the discussion from this week’s JavaScript chat (agendaSlack transcript).

Have a topic for discussion for the next meeting? Leave a suggested edit on next week’s agenda.

Node LTS 10.13.0

With the tagging of a new Node LTS 10.13.0 last week (from 8.x), both Gutenberg and Core builds are now running the latest version.

Data Module Generic Store API

refactoring of the data module has been merged, and it now exposes a new optional lower-level API for non-Redux stores, or more personalized instances of a Redux store.

Refer to the documentation for more information.

JavaScript Future Backwards Compatibility (and React)

Discussion: How can WordPress continue its commitment to backwards-compatibility while also not perpetually lagging behind the current version of dependencies (specifically, but not exclusively React).

Considerations:

  • Explore what it could look like to version WordPress scripts
  • Targeting the abstraction (wp.element) an intentional point in ensuring consistent version use.
  • Provide and/or surface codemods if it comes to the point of being forced to introduce a breaking change (Facebook does similarly with React)
  • Gutenberg’s deprecation pattern is not something which would necessarily continue post-5.0, but could serve as precedent for a future deprecation model

Action Items:

  • Compile a document which outlines expectations for a plugin author to anticipate and account for future compatibility, how and when a breaking change would be introduced

Implementing End-to-End Tests in Core

Continuation of discussion from last week.

Problem: How can Gutenberg’s end-to-end test suite be brought into the core development workflow?

Considerations:

  • Not blocking for a 5.0 release
  • Tracked at #45165
  • Having an end-to-end testing solution is useful for more than just the editor, and useful for more than just core development

Solutions:

Make some core part of the end-to-end solution available in @wordpress/scripts.

i18n Core Merge Update

@omarreiss shared the following update:

WP-CLI: Make sure wp i18n CLI command includes JavaScript translations when generating potfiles. [Done] Relevant PRs: https://github.com/wp-cli/i18n-command/pulls?q=is%3Apr+is%3Aclosed+author%3Aherregroen .
Meta: generate translations on translate.wordpress.org for core, themes and plugins. [MVP Done] Ticket: https://meta.trac.wordpress.org/ticket/3748
Meta: generate and serve JS language packs from translate.wordpress.org for core, themes and plugins. [Has patch] Ticket: https://meta.trac.wordpress.org/ticket/3876.
Core: Logic to load JS translations. [Done] Ticket: https://core.trac.wordpress.org/ticket/45103
Core: API to register JS translations for a script. Needs meta side of things to be finished. [Has patch] Ticket: https://core.trac.wordpress.org/ticket/45161
Make: Publish an update and a devnote on how the JS translations work. [todo @omarreiss / @herregroen]

@herregroen shares that for most plugin authors who host their plugins through the plugin repository, the change in workflow should be a matter of using wp_set_script_translations in place of where traditionally one would use wp_localize_script.

Reflecting on @wordpress/hooks

Prompt: As a retrospective of how wp.hooks has been used in the development of core, what feedback do developers have to share?

Feedback:

  • @youknowriad : “In general I’m thinking JavaScript is not a good fit for our hooks because JavaScript is a real time UI not like PHP where the flow is linear. The UI has to be Reactive and it’s very hard to achieve with hooks without pitfalls.”
  • @omarreiss : “I think it might also not be the pattern we want to teach the WP community.”
  • @herregroen : “I would give some thought to deprecating before release to send a clear message going forward. I think it would be confusing to have this familiar API and then never expand it and soon after start deprecating it.”
  • @aduth : “My general experience with them is that they’re not completely avoidable, but in the majority of cases I’ve seen them proposed, it’s been the wrong way to go about a problem with some serious non-obvious consequences and I’ve thus looked to them as a “footgun” (a tempting tool too easy to use wrongly)”
  • @adamsilverstein : “i’ve mainly tried using the withFilters HOC which seemed to work well, i’m not really sure where else hooks have been used in Gutenberg. I agree they can easily be misused and better approaches are often available.”
  • @schlessera : “It’s a procedural pattern that quickly breaks down once you go past procedural code, even in PHP.”

Takeaways:

There’s some general consensus that the pattern is not a good fit for how Gutenberg has been architected, and it’s assumed that this will apply as generally true for core features written in a similarly JavaScript-oriented approach.

It’s also true that there is usage of JavaScript hooks within Gutenberg for which a better alternative has surfaced. Thus, they will likely remain a tool, albeit one we should consider to avoid as much as possible, and limit exposure and advocation.

Action Items:

Consider a communication plan for the role of hooks (future agenda item).

#javascript

Dev Chat Agenda: November 7th (5.0 Week 6)

This is the agenda for the weekly devchat meeting on November 7th, 2018 at 20:00 UTC:

  • 5.0 Planning and Updates
  • Updates from focus leads and component maintainers
  • General announcements

If you have anything to propose to add to the agenda or specific items related to those listed above, please leave a comment below. Either way, we look forward to seeing you at the devchat this week!

This meeting is held in the #core channel in the Making WordPress Slack.

#5-0, #agenda, #core, #dev-chat

Classic Editor Plugin Support Window

The Gutenberg project is a fundamental shift for WordPress. We recognise that there will be a transition period as everyone adjusts to building plugins, themes, and sites using these new tools. To ease the transition for businesses and entrepreneurs, it’s been mentioned that the Classic Editor plugin would be maintained into the future. To give everyone more clarity on how long that’s likely to be, we’d like to add a date to how long the Classic Editor plugin will be supported.

The Classic Editor plugin will be officially supported until December 31, 2021.

During that time we will make sure that Gutenberg works seamlessly with existing WordPress infrastructure. That could include tools for testing and updating code, tutorials and additional documentation, or new compatibility layers. What is eventually created will be based on community feedback.

Since the Classic Editor plugin is central in this transition, we are considering including it with upgrades to WordPress 5.0. New WordPress installs would still add it manually, and we’ve included it in the Featured Plugins list to increase visibility. If you have thoughts on this idea, please leave a comment.

Q&A

  • What does “officially supported” mean? It will be guaranteed to work as expected in the most recent major release of WordPress, and the major release before it.
  • Can this date be extended? In 2021 we will evaluate continuing maintenance of the plugin, based on usage. We expect continued maintenance to be fairly trivial.
  • Will other fallbacks (for example, Custom Post Types, or Meta Boxes) work in Core for the next three years? While it will still be possible for CPTs and Meta Boxes to be marked incompatible with the block editor, future WordPress releases will move this functionality to the Classic Editor plugin. When this happens, WordPress will recommend that site owners install and activate the Classic Editor plugin when a fallback is triggered.

#5-0, #classic-editor

Meta Box Compatibility Flags

The new block editor has the ability to load meta boxes, to help plugins transition to the new Gutenberg platform. This compatibility functionality works fairly seamlessly with basic meta boxes, but more complex uses may require modification, particularly those that make heavy use of DOM-dependent JavaScript.

To help ensure end users have the best possible experience, there are two flags you can set when adding a meta box, which WordPress will use when determining when to load the block editor, or to fall back to the classic editor.

Flags

__block_editor_compatible_meta_box

This flag lets you set whether the meta box works in the block editor or not. Setting it to true signifies that the you’ve confirmed that the meta box works in the block editor, setting it to false signifies that it doesn’t. If the flag isn’t set, then WordPress 5.0 will assume that the meta box does work in the block editor.

__back_compat_meta_box

This flag lets you set whether the meta box is intended to be used in the block editor, or if it has been replaced by block-based functionality. Setting it to true signifies that this meta box should only be loaded in the classic editor interface, and the block editor should not display it. Setting it to false signifies that this meta box is intended to be loaded in the block editor. If the flag isn’t set, then WordPress 5.0 will assume that the meta box is intended to be loaded in the block editor.

Usage

These flags are used by passing them in the $args parameter of add_meta_box(), like so:

add_meta_box(
	'my-meta-box-id',
	__( 'My Meta Box', 'textdomain' ),
	'my_meta_box_callback',
	'post',
	'advanced',
	'default',
	array(
		'__block_editor_compatible_meta_box' => true,
		'__back_compat_meta_box'             => false,
	)
);

Fallback Warnings

WordPress 5.0 also contains a developer preview of a fallback warning. If you set WP_DEBUG to true, then create a meta box with __block_editor_compatible_meta_box set to false, and __back_compat_meta_box either undefined, or set to false as well, this warning will show in the classic editor.

Screen shot of a demo meta box showing the fallback warning.

This warning is currently intended to be a developer preview, hence why it’s hidden behind the WP_DEBUG flag, and requires a particular combination of the compatibility flags to be set. The wording and appearance of the warning will likely change in future WordPress versions, but it’s ultimately intended to help end users identify which plugin is responsible for a meta box.

If you register your meta box with the __back_compat_meta_box set to true, then this warning will never be displayed with your meta box, now, or in future WordPress releases.

Future Changes

Future versions of WordPress may change how they behave when these flags are set. For example, WordPress 5.0 will silently fall back to the classic interface when an incompatible meta box is encountered. Classic editor code will likely be moved to the Classic Editor plugin in the future, however, so those future WordPress versions would require the Classic Editor plugin to be installed before it could automatically fall back. Any such changes would be posted well in advance, to ensure there’s plenty of warning for testing changes.

#5-0, #dev-notes

Core Privacy Agenda – 7 November 2018

When/Where: Join us in #core-privacy on Making WordPress Slack from 1500-1600 UTC

Agenda:

  • We need a facilitator and note-taker for today (@allendav is on travel/AFK)
  • New Meeting Time discussion @desrosj
  • Tickets
  • Needs-privacy-review tag – Update from @garrett (meta:3896)
    • “wrote the patch and it’s now awaiting a commit. There’s two additional items after commit which is including links but we’ll hold on that until the tag starts to get some usage”
  • Raising awareness of core privacy work and meetings
    • Update from Rian re marketing newsletter — getting the word out about Office Hours, our need for developers and end-user feedback
  • “What is privacy in our context?”
    • What is privacy in the sense of what areas do we look at in our work @idea15
    • Separating the theory from the practice (e.g. our dev guidelines)
    • Update on working with Chris Tiezel for cross-platform definitions @idea15

Items postponed to next week:

  • WP mobile app permissions and trackers (@allendav)
  • Trackers on WP.org footer (@allendav)

What the Cool Privacy Kids Are Reading / Trying This Week:

Upcoming WordCamp (and other Event) Privacy Talks:

  • Planned talks
  • Opportunities

Helpful links:

#privacy #core-privacy

Dev Chat Summary: October 31st (5.0 Week 5)

This post summarizes the dev chat meeting from October 31st 🎃 (agenda, Slack archive).

5.0 Planning and Updates

  • We have a lot of PRs that need review, so please pick up one or two if that’s something you excel at. 🙂 A code review team is being create on Github to help call these out.
  • Bug scrubs are happening all week if you want to volunteer to help close a bug or test to provide more information.
  • Beta 2 came out last week and was accompanied by an update to the timeline that gives us more beta cycles.
  • We have some back compat issues in the media component for 5.0 and could use more help there.
  • Documentation has been split into two different tickets, one for User docs and Design/Dev docs.
  • Gary posted some new dev notes about Block Editor Filters for this release. These filters exist to help transition to the block editor.

Component and Focus Updates

  • The Gutenberg team released v4.2 which mostly includes performance enhancements and bug fixes. It also concludes the cycle for the formatting API.
  • Core PHP is working on an updated roadmap for Servehappy, and shared a continued need for WSOD testing.
  • Core Javascript is working on a plan to add End 2 End (E2E) tests for plugins and Core as it is used in Gutenberg.

Announcements and Open Floor

Next meeting

The next meeting will take place on Wednesday, November 7 20:00 UTC in the #core Slack channel. Please feel free to drop in with any updates or questions. If you have items to discuss but cannot make the meeting, please leave a comment on the upcoming agenda post so that we can take them into account.

#5-0#a11y#core#core-editor#core-js#core-media#core-php#core-restapi#dev-chat#gutenberg#summary#team-reps

PHP Meeting Recap – October 29th

This recap is a summary of our previous PHP meeting. It highlights the ideas and decisions which came up during that meeting, both as a means of documenting and to provide a quick overview for those who were unable to attend.

You can find this meeting’s chat log here.

Chat Summary

  • There was only very little presence/activity on October 29th.
  • Probably as a result of this, @nerrad asked whether it would make sense to “pause” the #core-php meetings until after WordPress 5.0 has been released. A lot of people have to focus on making their products/customer sites Gutenberg-ready and cannot invest the same amount of time into working on Servehappy while this is going on.
  • @nerrad also hinted at the possibility that the current lack of testers for WSOD protection could be due to the same reasons.
  • While discussing what the blockers actually are and what parts of Servehappy could be considered “ready to go”, we agreed that it would be useful to post a “State of Servehappy” recap post. @schlessera will prepare a draft for this to discuss.

Next week’s meeting

  • Next meeting will take place on Monday, November 5th, 2018 at 15:00 UTC in #core-php.
  • Agenda: Open floor.
  • If you have suggestions about this but cannot make the meeting, please leave a comment on this post so that we can take them into account.

#php, #servehappy, #summary