Add a filter to the translation file location for script localisation

[johnbillion]

In [43825] (#45103), the load_script_textdomain() function was introduced as part of the changes that allow JavaScript files to register and use translated strings.

This function doesn't pass its return value through a filter, which means it's not possible to override the paths used for translation files, nor is it possible to inspect its behaviour for debugging purposes. The latter is particularly noteworthy because this is brand new functionality that plugin and theme authors will be attempting to implement, and being able to debug what translation files are being loaded is valuable.

I propose that this function is altered so it operates a little more similarly to the existing load_plugin_textdomain() and load_textdomain() functions for gettext translation files.

cc @omarreiss @herregroen

[johnbillion]

45425.patch​ adds a load_script_translation() function which allows the script translation file location to be filtered and then loads and returns the file's contents, similarly to how load_textdomain() operates.

This allows, for example, the Query Monitor plugin to add support for debugging script translation file loading.

[herregroen]

@johnbillion sounds like a good idea. Patch looks good as well.

I'm all in favour.

[swissspidy]

You're totally right that people should be able to debug this.

Patch looks good to me as well.

[omarreiss]

Seems like a safe and good commit to me. I've asked @pento for signoff.

[johnbillion]

This actually isn't as optimal as it could be because the potential translation file paths aren't exposed, but it works the same way that load_textdomain() does so let's get it into 5.0 and iterate on it in a point release.

[swissspidy]

#45320 was marked as a duplicate.

[strategio]

Improved patch to introduce the filter pre_load_script_translation

[strategio]

Following suggestion from @swissspidy in #45320, I improved the patch to include a filter pre_load_script_translation which would allow to preload the translations (not necessarily from a file).

[swissspidy]

In 45425.diff​

• Improve inline docs
• Add filter at the end of the function

[pento]

As this patch is still evolving, and I'm not wild about adding functionality during RC, I'm bumping this to 5.0.1.

[dimadin]

I am not sure should this be in this separate ticket or handled here. Before JavaScript translations and WP 5.0 (since [3425] and WP 2.0.1), every string was passed through some of ​gettext filters. This enabled manipulations of translations but also of originals in English (e.g. change some text). There are ​over 500 plugins in WP.org repository that use them. They are also ​used by Serbian localization to ship both Serbian Cyrillic and Serbian Latin version in one package.

We don't have anything like this with JavaScript translations. They aren't filterable at all (this is the reason there is no WP 5.0 in Serbian Latin). One ​option is to filter strings on JavaScript side. But plugins that already use those filters will not work there, they need to port their filters to JavaScript version (and some implementations can't be ported at all) and have both PHP and JavaScript versions.

Since we already load JavaScript translations in PHP, can we loop through those translations and then apply gettext filters? One problem I see already is that for plural strings since we can't use ​ngettext filter.

[swissspidy]

@dimadin Correct, because of plural forms we cannot do this on the PHP side. That's one of the reasons we have this new JS functionality in the first place.

Instead, I suggested filters for these on the JS side in ​https://github.com/WordPress/gutenberg/pull/12517

[strategio]

Hi,

Having filters on the JS side (as suggested by @swissspidy and @dimadin) does not exclude having filters in PHP.

We have extended our solution to translate JS strings by overriding the JED files, and we will rely on the new filters added here (mostly load_script_textdomain_file). Could we have a confirmation that it will be included?

Thanks!

[swissspidy]

We could probably rename load_script_textdomain_file to load_script_translation_file for consistency, but otherwise 45425.diff​ is good to go IMO.

@ocean90 @johnbillion @pento If anyone wants to do a final review, that'd be great :-)

---

Having filters on the JS side does not exclude having filters in PHP.

Of course not, that's why this ticket and the patches exist :-)

Could we have a confirmation that it will be included?

I think it's fair to say that there aren't any guarantees with open source projects :-)

This ticket is currently slated for the 5.0.2 milestone and is something that just makes sense, so it's definitely likely to be included in that release.

[dimadin]

Replying to swissspidy:

@dimadin Correct, because of plural forms we cannot do this on the PHP side. That's one of the reasons we have this new JS functionality in the first place.

I did research. There are ​less than 60 plugins in WP.org repository that use ngettext filter. Even smaller number of those actually accept fourth parameter, number used for determining what plural form to use. Of those that accept it, not all use it. So basically many are filtering plural strings the same way they filter standard strings, without paying attention is that singular or plural form (they even use the same callback functions).

I'm attaching function I made that is callback on proposed load_script_translation filter (from attachment:45425.diff​) and that loops through all strings from JavaScript translations and applies gettext or gettext_with_context filter on them. If string has plural form, it applies gettext/gettext_with_context filter on each plural form. This will restore most uses of existing gettext filters, only those that really need number for plural strings will need JS implementation.

[ocean90]

Feedback for 45425.diff​:

• Let's rename load_script_translation() to load_script_translations() (plural).
• Also, load_script_textdomain_file to load_script_translation_file.
• The @since tags need an update
• "textdomain" => "text domain"

[ocean90]

In 44232:

I18N: Introduce load_script_translations() as a wrapper for loading and filtering translation data for JavaScript files.

• Introduces pre_load_script_translations to short-circuit the function.
• Introduces load_script_translation_file to filter the file path for loading script translations.
• Introduces load_script_translations to filter the JSON-encoded translation data.

Props johnbillion, strategio, swissspidy, dimadin, ocean90.
See #45425.

[SergeyBiryukov]

In 44316:

I18N: Introduce load_script_translations() as a wrapper for loading and filtering translation data for JavaScript files.

• Introduces pre_load_script_translations to short-circuit the function.
• Introduces load_script_translation_file to filter the file path for loading script translations.
• Introduces load_script_translations to filter the JSON-encoded translation data.

Props johnbillion, strategio, swissspidy, dimadin, ocean90.
Merges [44232] to trunk.
Fixes #45425.