Skip to content

Premium Analytics: emit gettext stubs for the widget.json strings - #53850

Merged
retrofox merged 5 commits into
trunkfrom
add/widget-json-gettext-stubs
Oct 21, 2026
Merged

retrofox merged 5 commits into
trunkfrom
add/widget-json-gettext-stubs

Conversation

@retrofox

@retrofox retrofox commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor

Part of WOOA7S-2175 (WOOA7S-2174, task T0.1).

Proposed changes

The widget.json strings reach a catalog

Every widget title, description, help note, and settings label declared in widget.json renders in English in every locale.

wp-build copies them into build/widgets/registry.php as plain literals, and the registry translates them at hydration with _x( value, context, domain ), the contexts coming from src/widget-i18n.json.

But no extractor reads widget.json or registry.php (wp i18n make-pot knows block.json, not widget.json), so the (msgid, msgctxt) pairs never reach a catalog and every lookup misses.

emit-widget-strings, a new bin in wp-build-polyfills next to stamp-textdomains, walks every widgets/*/widget.json in lockstep with the schema and writes build/widgets/widget-strings.php: one _x() per translatable value, with the exact context the registry looks up and the widget's text domain, or the package's extra.textdomain for a widget that declares none.

Nothing loads the file; it exists for gettext extraction, like core's wp-admin/includes/continents-cities.php.

Once a catalog carries the strings, the registry's lookups succeed and the REST record arrives translated; the client changes nothing.

Premium Analytics, WooCommerce Stats, Ads and VideoPress run it after wp-build. The three consumer packages point it at this package's schema, which their widgets are translated with. stamp-textdomains shares the new text-domain resolver.

Upstream, WordPress/gutenberg#80564 proposes the same file for the Gutenberg plugin's own widgets as a private build step, and native wp i18n make-pot support waits for widget-i18n.json to reach core. The bin goes the day it ships for consumers.

Related product discussion/links

Does this pull request change what data or activity we track or use?

No.

Testing instructions

Clean

rm -rf projects/packages/woocommerce-stats/build
rm -rf projects/packages/ads/build
rm -rf projects/packages/videopress/build
rm -rf projects/packages/premium-analytics/build

Build

jetpack build --deps packages/premium-analytics
jetpack build packages/woocommerce-stats
jetpack build packages/ads
jetpack build packages/videopress

Each package now has build/widgets/widget-strings.php, one _x() per line: 143 in Premium Analytics, 90 in WooCommerce Stats, 13 in Ads, 4 in VideoPress. php -l passes on each.

Premium Analytics

<?php
/**
 * Gettext reference stub for the widget.json metadata of the widgets in this
 * package: one call per translatable value, with the context the widget
 * registry looks up at hydration. Generated by emit-widget-strings; never loaded.
 */

_x( 'All-time stats', 'widget title', 'jetpack-premium-analytics-pkg' );
_x( 'Lifetime totals for your site — views, visitors, posts, and comments.', 'widget description', 'jetpack-premium-analytics-pkg' );
_x( 'Your totals since you started tracking — views, visitors, posts, and comments.', 'widget help content', 'jetpack-premium-analytics-pkg' );
_x( 'Year in review', 'widget title', 'jetpack-premium-analytics-pkg' );
// ...

WooCommerce Stats

<?php
/**
 * Gettext reference stub for the widget.json metadata of the widgets in this
 * package: one call per translatable value, with the context the widget
 * registry looks up at hydration. Generated by emit-widget-strings; never loaded.
 */

_x( 'Average items per order', 'widget title', 'jetpack-woocommerce-stats-pkg' );
_x( 'Show the average number of products per order over a set period of time.', 'widget description', 'jetpack-woocommerce-stats-pkg' );
_x( 'Show the average number of products per order over a set period of time.', 'widget help content', 'jetpack-woocommerce-stats-pkg' );
_x( 'Chart type', 'widget attribute label', 'jetpack-woocommerce-stats-pkg' );
// ...

VideoPress

<?php
/**
 * Gettext reference stub for the widget.json metadata of the widgets in this
 * package: one call per translatable value, with the context the widget
 * registry looks up at hydration. Generated by emit-widget-strings; never loaded.
 */

_x( 'Top videos', 'widget title', 'jetpack-videopress-pkg' );
_x( 'Your most played VideoPress videos, sourced from Jetpack Stats.', 'widget description', 'jetpack-videopress-pkg' );
_x( 'The published videos your visitors watched most often, sorted by views.', 'widget help content', 'jetpack-videopress-pkg' );
_x( 'Learn more', 'widget help link label', 'jetpack-videopress-pkg' );

Ads

<?php
/**
 * Gettext reference stub for the widget.json metadata of the widgets in this
 * package: one call per translatable value, with the context the widget
 * registry looks up at hydration. Generated by emit-widget-strings; never loaded.
 */

_x( 'Ads summary', 'widget title', 'jetpack-ads-pkg' );
_x( 'Track ads served, average CPM, and revenue over the selected period.', 'widget description', 'jetpack-ads-pkg' );
_x( 'Impressions, average CPM, and the revenue they earned over the selected period.', 'widget help content', 'jetpack-ads-pkg' );
_x( 'Learn more', 'widget help link label', 'jetpack-ads-pkg' );
_x( 'Chart type', 'widget attribute label', 'jetpack-ads-pkg' );
_x( 'Line chart', 'widget attribute option label', 'jetpack-ads-pkg' );
_x( 'Bar chart', 'widget attribute option label', 'jetpack-ads-pkg' );
_x( 'WordAds earnings', 'widget title', 'jetpack-ads-pkg' );
_x( 'Your WordAds earnings by period, with amounts and payment status.', 'widget description', 'jetpack-ads-pkg' );
_x( 'What each billing month earned from programmatic ads, and whether it has been paid. Whole months only, so the month in progress isn’t listed.', 'widget help content', 'jetpack-ads-pkg' );
_x( 'All-time balance', 'widget title', 'jetpack-ads-pkg' );
_x( 'Your WordAds earnings at a glance — total earnings, amount paid, and outstanding balance.', 'widget description', 'jetpack-ads-pkg' );
_x( 'What your ads have earned since you started, what has been paid out, and what is still owed. Lifetime totals — these don’t follow the date selection. Payments go out once the outstanding amount reaches $100.', 'widget help content', 'jetpack-ads-pkg' );

Extraction

wp i18n make-pot build/widgets /tmp/widgets.pot --ignore-domain --skip-js --skip-audit

In projects/packages/premium-analytics, this yields 143 entries, each with its msgctxt: widget title, widget description, widget help content, widget help link label, widget attribute label, widget attribute option label.

Example:

msgid ""
msgstr ""
"Project-Id-Version: \n"
"Report-Msgid-Bugs-To: \n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"POT-Creation-Date: 2026-10-20T14:49:26+00:00\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"X-Generator: WP-CLI 2.9.0\n"

#: widget-strings.php:8
msgctxt "widget title"
msgid "All-time stats"
msgstr ""

#: widget-strings.php:9
msgctxt "widget description"
msgid "Lifetime totals for your site — views, visitors, posts, and comments."
msgstr ""

#: widget-strings.php:10
msgctxt "widget help content"
msgid "Your totals since you started tracking — views, visitors, posts, and comments."
msgstr ""

#: widget-strings.php:11
msgctxt "widget title"
msgid "Year in review"
msgstr ""

Translation

Translations arrive with the first translate.wordpress.org import of a release that ships the stub, so a local check needs a hand-made catalog: a .po with a msgctxt "widget title" entry for one title, wp i18n make-mo, the .mo dropped into wp-content/languages/plugins/ under the plugin's domain (jetpack-<locale>.mo, the alias i18n-map.php declares), the site switched to that locale.

GET /wp-json/wpcom/v2/widget-modules then returns that title translated, and so does the dashboard.

Tests

pnpm run test in projects/packages/wp-build-polyfills.

@github-actions

github-actions Bot commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor

Are you an Automattician? Please test your changes on all WordPress.com environments to help mitigate accidental explosions.

  • To test on WoA, go to the Plugins menu on a WoA dev site. Click on the "Upload" button and follow the upgrade flow to be able to upload, install, and activate the Jetpack Beta plugin. Once the plugin is active, go to Jetpack > Jetpack Beta, select your plugin (Jetpack or WordPress.com Site Helper), and enable the add/widget-json-gettext-stubs branch.
  • To test on Simple, run the following command on your sandbox:
bin/jetpack-downloader test jetpack add/widget-json-gettext-stubs
bin/jetpack-downloader test jetpack-mu-wpcom-plugin add/widget-json-gettext-stubs

Interested in more tips and information?

  • In your local development environment, use the jetpack rsync command to sync your changes to a WoA dev blog.
  • Read more about our development workflow here: PCYsg-eg0-p2
  • Figure out when your changes will be shipped to customers here: PCYsg-eg5-p2

@github-actions

github-actions Bot commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor

Thank you for your PR!

When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:

  • ✅ Include a description of your PR changes.
  • ✅ Add a "[Status]" label (In Progress, Needs Review, ...).
  • ✅ Add testing instructions.
  • ✅ Specify whether this PR includes any changes to data or privacy.
  • ✅ Add changelog entries to affected projects

This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖


Follow this PR Review Process:

  1. Ensure all required checks appearing at the bottom of this PR are passing.
  2. Make sure to test your changes on all platforms that it applies to. You're responsible for the quality of the code you ship.
  3. You can use GitHub's Reviewers functionality to request a review.
  4. When it's reviewed and merged, you will be pinged in Slack to deploy the changes to WordPress.com simple once the build is done.

If you have questions about anything, reach out in #jetpack-developers for guidance!


Jetpack plugin:

No scheduled milestone found for this plugin.

If you have any questions about the release process, please ask in the #jetpack-releases channel on Slack.

@jp-launch-control

jp-launch-control Bot commented Oct 20, 2026 •

Copy link
Copy Markdown

Code Coverage Summary

Coverage changed in 1 file.

File Coverage Δ% Δ Uncovered
projects/packages/wp-build-polyfills/bin/stamp-textdomains.js 40/40 (100.00%) 0.00% 0 💚

3 files are newly checked for coverage.

File Coverage
projects/packages/wp-build-polyfills/bin/emit-widget-strings-lib.js 147/149 (98.66%) 💚
projects/packages/wp-build-polyfills/bin/emit-widget-strings.js 38/38 (100.00%) 💚
projects/packages/wp-build-polyfills/bin/package-textdomain-lib.js 37/37 (100.00%) 💚

Full summary · PHP report · JS report

@retrofox
retrofox marked this pull request as ready for review October 20, 2026 14:50
@retrofox
retrofox requested a review from a team as a code owner October 20, 2026 14:50
@retrofox retrofox added [Status] Needs Review This PR is ready for review. and removed [Status] In Progress labels Oct 20, 2026
dognose24
dognose24 previously approved these changes Oct 20, 2026

@dognose24 dognose24 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. The emitter mirrors what the registry does at hydration, so the (msgid, msgctxt, domain) triples it writes are the ones the lookups will ask for.

What I checked:

  • walkSchema against core's translate_settings_using_i18n_schema(): string leaf, list via schema[0], keyed map with the * fallback, empty strings skipped. attributes and elements are lists in both widget.json and the schema, and the six contexts are the ones translate_widget_metadata() uses.
  • Domains line up: the ads, VideoPress and WooCommerce Stats manifests all declare textdomain, and the Premium Analytics ones fall back to extra.textdomain, the same fallback register_widget_types_from_manifest() applies.
  • The stub lands in build/widgets/, which every one of the four packages marks production-include, so it ships the way the JS i18n stubs from strip-unminified-prod already do and reaches the same extraction.
  • Single-quoted PHP escaping covers exactly \ and '; a run with nothing to emit removes a stale stub; --schema, --widgets, --out, --domain are all exercised by the bin tests against the real executable.
  • stamp-textdomains keeps its behaviour through the shared resolver.

One thing to add before merging: a plugins/premium-analytics changelog entry (inline). Two optional notes inline.

Significance: patch
Type: bugfix

Premium Analytics: Make widget titles, descriptions, help notes and settings labels translatable.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

plugins/premium-analytics bundles both premium-analytics and woocommerce-stats, and translated widget metadata is something its users notice, so it wants an entry too (no product prefix there). plugins/videopress does not: Top videos only renders inside the Premium Analytics dashboard, which that plugin does not ship.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added in 008a6e2, fixed and no prefix. Agreed on plugins/videopress: nothing there reaches the widget.

Comment on lines +1 to +14
/**
* Library for the `emit-widget-strings` bin.
*
* wp-build copies each widget's `widget.json` metadata into
* `build/widgets/registry.php` as plain literals, and the widget registry
* translates them at hydration with `_x( value, context, domain )`, the
* contexts coming from the widget i18n schema (`widget-i18n.json`). No
* extractor reads either file, so on their own the (msgid, msgctxt) pairs
* never reach a catalog: `wp i18n make-pot` knows `block.json` natively,
* `widget.json` not yet. This emits a PHP file nothing loads, holding one
* `_x()` per value with the exact context and domain the registry will look
* up, the way core's `wp-admin/includes/continents-cities.php` exists for
* gettext alone.
*/

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Optional: this header, the bin header, the README section and dashboard-widgets.md are four copies of the same explanation. One sentence here plus a pointer to the README keeps it within the comment budget, and leaves a single place to update when wp i18n make-pot learns widget-i18n.json.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Trimmed in b7d2b3c: the README owns the explanation and the flag defaults; the lib and bin headers keep one sentence and a pointer, and the Premium Analytics doc names the lane and points at the README.

Comment on lines +128 to +140
it( 'covers every Premium Analytics widget with contexts the schema names', () => {
const { entries, widgets } = collectWidgetStrings(
path.join( PA_DIR, 'widgets' ),
SCHEMA,
'jetpack-premium-analytics-pkg'
);
const contexts = new Set( schemaContexts( SCHEMA ) );
const titles = entries.filter( entry => entry.context === 'widget title' );
assert.ok( widgets > 0 );
assert.equal( titles.length, widgets, 'one title per widget' );
assert.ok( entries.every( entry => contexts.has( entry.context ) ) );
assert.ok( entries.every( entry => entry.domain === 'jetpack-premium-analytics-pkg' ) );
} );

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Optional: this ties the wp-build-polyfills suite to Premium Analytics' widgets/ layout and schema path. Fine inside the monorepo, just worth knowing that a Premium Analytics reshuffle will fail here first.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Decoupled in b771bb5: the suite uses an inline schema fixture with every shape the walk handles, and the sync check against the Premium Analytics tree is gone. Two of its assertions restated the inputs, and "one title per widget" is that package's invariant, not the emitter's.

lib, bin and PA docs keep one sentence and a pointer
an inline schema fixture replaces the Premium Analytics sync check
@retrofox
retrofox requested a review from dognose24 October 21, 2026 09:02
@retrofox
retrofox merged commit 929821b into trunk Oct 21, 2026
131 checks passed
@retrofox
retrofox deleted the add/widget-json-gettext-stubs branch October 21, 2026 10:43
@github-actions github-actions Bot removed the [Status] Needs Review This PR is ready for review. label Oct 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants