Skip to content

Dashboard Widgets: emit a gettext strings file for widget.json metadata - #80564

Draft
retrofox wants to merge 2 commits into
trunkfrom
add/wp-build-widget-metadata-strings
Draft

retrofox wants to merge 2 commits into
trunkfrom
add/wp-build-widget-metadata-strings

Conversation

@retrofox

@retrofox retrofox commented Jul 22, 2026 •

Copy link
Copy Markdown
Contributor

What?

Adds a private build step that generates build/widgets/widget-strings.php, with one _x() call per translatable widget.json metadata value (title, description, help.content, help.links[].label, actions[].label, keywords[]). The file is never loaded at runtime; it exists so gettext extraction tooling sees the strings.

Following the review discussion, the generation lives in the repo's private build scripts (tools/build-scripts/); wp-build is untouched.

The bundled widgets also switch their textdomain from default to gutenberg, so the strings can reach the plugin translation project on wp.org before the feature lands in core.

Fixes #80561.

Related to #77629

Why?

The runtime translation pipeline already exists: gutenberg_translate_widget_metadata() translates the hydrated registry on init through translate_settings_using_i18n_schema() with the contexts in lib/experimental/dashboard-widgets/widget-i18n.json.

But the strings never reach a catalog: registry.php carries plain literals, and no extraction tooling understands widget.json (unlike block.json, which wp i18n make-pot and the wp.org importer support natively). So widget metadata renders untranslated in every non-English locale, including the widgets bundled in this repo.

Native make-pot support is the endgame once the format stabilizes; this generated file bridges the window with the same (msgid, msgctxt, textdomain) triples a native extractor would produce, so it can be deleted then without changing the resulting POT.

How?

  • New tools/build-scripts/packages/generate-widget-strings.mjs, invoked from tools/build-scripts/build.mjs right after the wp-build step, with a generate-widget-strings alias in the workspace package.json.
  • The emitter is schema-driven: it walks each widget.json in lockstep with widget-i18n.json, mirroring the translate_settings_using_i18n_schema() traversal the runtime uses. There is no duplicated context map to keep in sync.
  • Widgets without a textdomain are skipped, matching the runtime no-op. Entries are deduplicated per (value, context, textdomain) and escaped as single-quoted PHP literals.
  • When there is nothing to emit, a leftover widget-strings.php is removed, so stale strings never linger in a POT.
  • The bundled widget.json files declare "textdomain": "gutenberg": with default, the plugin translation project filters the strings out, and core catalogs carry no entries for these context-qualified lookups.

Testing Instructions

  1. Run node tools/build-scripts/packages/generate-widget-strings.mjs (it also runs as part of npm run build).
  2. Inspect build/widgets/widget-strings.php: one _x() per metadata value:
<?php
_x( 'Activity', 'widget title', 'gutenberg' );
_x( 'Displays recently published posts, scheduled posts, and recent comments.', 'widget description', 'gutenberg' );
_x( 'Recent publishing and comment activity on this site.', 'widget help content', 'gutenberg' );
// ...
  1. Confirm the runtime never loads it: build/widgets.php only requires registry.php and the per-widget asset files.
  2. Run wp i18n make-pot build/widgets widgets.pot --ignore-domain and confirm the strings appear, with their contexts, in the generated POT.
  3. Stale cleanup: blank every textdomain in widgets/*/widget.json, re-run the emitter, and confirm the generated file is deleted; restore with git checkout -- widgets.

Follow-ups

  • Propose native widget.json extraction to wp-cli/i18n-command once the metadata format stabilizes, and remove this build step.

@retrofox retrofox added Internationalization (i18n) Issues or PRs related to internationalization efforts [Package] wp-build /packages/wp-build [Feature] Dashboard WordPress admin dashboard, widget framework, and layout customization labels Jul 22, 2026
@retrofox retrofox self-assigned this Jul 22, 2026
@github-actions

github-actions Bot commented Jul 22, 2026 •

Copy link
Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: retrofox <retrofox@git.wordpress.org>
Co-authored-by: chihsuan <chihsuan@git.wordpress.org>
Co-authored-by: youknowriad <youknowriad@git.wordpress.org>
Co-authored-by: jsnajdr <jsnajdr@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

@github-actions

Copy link
Copy Markdown

Size Change: 0 B

Total Size: 7.75 MB

compressed-size-action

@retrofox

retrofox commented Jul 22, 2026 •

Copy link
Copy Markdown
Contributor Author

#79701 landed the runtime side of widget metadata translation and left string extraction pending, as noted in #77629 (comment): wp i18n make-pot learning to scan widget.json, the same dependency block.json had.

That native support remains the endgame once the format stabilizes; this generated file bridges the window by emitting the same (msgid, msgctxt, textdomain) triples a native extractor would produce from widget-i18n.json, so it can be deleted then without changing the resulting POT.

@github-actions

Copy link
Copy Markdown

Flaky tests detected in 6c2f330.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/29936561294
📝 Reported issues:

@chihsuan chihsuan left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Thanks for working on this! @retrofox I left a few inline suggestions around stale output, watch mode, and keeping the schema-sync test future-proof. The focused wp-build tests pass locally.

Comment thread packages/wp-build/lib/build.mjs Outdated
);

if ( calls.length === 0 ) {
return;

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I wonder if it would be worth removing an existing widget-strings.php before returning here. Otherwise, after the last textdomain or translatable value is removed, strings from an earlier build could remain in the generated POT.

Comment thread packages/wp-build/lib/build.mjs Outdated
generateRoutesRegistry( activeRoutes, phpReplacements ),
generateRoutesPhp( activeRoutes, phpReplacements ),
generateWidgetRegistry( widgets, phpReplacements ),
generateWidgetStrings( widgets, phpReplacements ),

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Would it make sense to regenerate the widget registry and strings file when widget.json changes in watch mode too?

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.

Yes, it could be, but I'd like teo consider it in a separate PR. This change is out of scope for this PR.

'experimental',
'dashboard-widgets',
'widget-i18n.json'
);

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I’m wondering whether this sync check might fit better on the Gutenberg/dashboard-widgets side. That would help keep the generic @wordpress/build tests independent of Gutenberg’s internal lib/experimental directory structure.

Comment thread packages/wp-build/README.md Outdated
- `build/widgets/{widget-name}/widget.min.js` + `widget.js` — Bundled metadata (ESM)
- `build/widgets/{widget-name}/widget.min.asset.php` — Asset metadata for widget module
- `build/widgets/registry.php` — Widget registry data
- `build/widgets/widget-strings.php` — Gettext calls for the translatable `widget.json` metadata, for extraction tooling; never loaded at runtime. Generated when a widget declares a `textdomain`.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Tiny nit: because the domain may also come from wpPlugin.textdomain, perhaps this could say:
Generated when at least one widget has a resolved textdomain and a translatable metadata value.?

...schema.help.links.map( ( link ) => link.label ),
...schema.actions.map( ( action ) => action.label ),
...schema.keywords,
].sort();

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I like the schema-drift check here. I wonder if collecting the schema’s string leaves recursively would make it a little more future-proof. With the current explicit paths, a newly added field such as subtitle could be omitted from both this list and the extractor while the test still passes.

@youknowriad

Copy link
Copy Markdown
Contributor

How do we do this for block.json, theme.json and things like that?

@jsnajdr

jsnajdr commented Jul 23, 2026

Copy link
Copy Markdown
Member

How do we do this for block.json, theme.json and things like that?

The wp-cli i18n make-pot command that does the string extraction has a direct support for these files. There is a block-i18n.json schema file that defines the extracted fields, and the command does the extraction.

If widget.json is a new file type in Core that's stable and is going to stay, then patching the i18n-command repo is the right thing to do. Same applies to other new .json files related to the routing framework.

For experimental/unstable file types, generating an auxiliary PHP file is a good idea. But keep in mind that the name of the file that a string was extracted from is an integral part of the translation string definition, and will be used when producing a set of translations files that are loaded at runtime. Who and when loads the widget.json file at runtime?

@youknowriad

Copy link
Copy Markdown
Contributor

For experimental/unstable file types, generating an auxiliary PHP file is a good idea.

This is my issue with this PR, It adds an API and updates wp-build for something we know is not the final desired result.

@jsnajdr

jsnajdr commented Jul 23, 2026

Copy link
Copy Markdown
Member

It adds an API and updates wp-build for something we know is not the final desired result.

Can we then move the functionality outside wp-build, maybe as a step in the tools/build-scripts/build.mjs script? Then it's outside the published wp-build package, local only for Gutenberg. Or do we need this also for widgets outside Gutenberg, e.g., in Woo?

@retrofox retrofox added the [Type] Enhancement A suggestion for improvement. label Jul 24, 2026
@retrofox
retrofox requested a review from manzoorwanijk as a code owner July 24, 2026 12:50
@retrofox

Copy link
Copy Markdown
Contributor Author

After looking at the approach as a whole, I'm not sure what the logical next step is.

In fact, I'm not sure we're in a position to tackle the translation problem at all, given how experimental and in active development the Widgets API still is.

Two things do seem clear to me:

  • We don't want to couple any part of the translation process into wp-build.
  • For an API that today I wouldn't consider stable, patching tools like wp i18n make-pot is more than premature.

We can clean the changes out of wp-build and move the generation to tools/, internal and private to the plugin. I've restructured the PR that way.

But I wonder now whether it's worth it for an experimental feature, since in the worst case the translatable widget metadata simply renders untranslated.

Also, if we want to see these strings actually getting translated now, the bundled widgets would have to use the gutenberg textdomain (with default, nothing reaches the plugin's translation project, and core's catalogs don't carry these context-qualified strings). Maybe that's not worth it either.

Yes @jsnajdr. The goal is that consumers/plugins can declare widget metadata in their JSON files and have the framework take care of the whole pipeline, translation included.

As with other pieces of this implementation, in the meantime third-party developers will have to roll their own local, temporary implementations, along the lines of the private script this PR adds.

For now the PR stands as:

  • wp-build untouched
  • a private generation step in tools/build-scripts/
  • and the gutenberg textdomain on the bundled widgets.

Something to keep analyzing.

Who and when loads the widget.json file at runtime?

The build compiles it into registry.php, and the strings are translated server-side when the registry is hydrated on init (translate_settings_using_i18n_schema() with each widget's textdomain). So the name of the generated file is only a POT reference.

It doesn't participate in any runtime lookup.

@retrofox retrofox changed the title wp-build: emit a gettext strings file for widget.json metadata Dashboard Widgets: emit a gettext strings file for widget.json metadata Jul 24, 2026
@retrofox

Copy link
Copy Markdown
Contributor Author

Thanks, @chihsuan. I've changed the approach by removing the code from wp-build. More in the comment above.

@retrofox
retrofox force-pushed the add/wp-build-widget-metadata-strings branch from bfa1b10 to e5282f1 Compare September 19, 2026 09:44
@github-actions github-actions Bot removed the [Package] wp-build /packages/wp-build label Sep 19, 2026
@github-actions

github-actions Bot commented Sep 19, 2026 •

Copy link
Copy Markdown

🤖 PR meta 🤖

📦 Bundle size

Size Change: 0 B

Total Size: 8.21 MB

e5282f1 Run

⚡ Performance

Show the results

Client side metrics exclude the server response time.

front-end-block-theme

Metric 7ab5137 trunk % Change
timeToFirstByte 55.15 ms +12.78% -1.09% 55.95 ms +14.21% -2.95% -1.43%
largestContentfulPaint 98 ms +2.04% -10.2% 96 ms +0% -4.17% 2.08%
lcpMinusTtfb 34.85 ms +22.96% -3.16% 34.25 ms +22.48% -6.86% 1.75%
wpBeforeTemplate 28.03 ms +15.34% -2.89% 28.07 ms +17.56% -1.5% -0.14%
wpTemplate 24.05 ms +6.15% -4.03% 23.82 ms +5.5% -3.23% 0.97%
wpTotal 51.38 ms +13.64% -0.72% 52.49 ms +13.16% -3.05% -2.11%
wpMemoryUsage 7.53 MB +0% -0% 7.49 MB +0% -0% 0.46%
wpDbQueries 17 +0% -0% 17 +0% -0% 0%

front-end-classic-theme

Metric 7ab5137 trunk % Change
timeToFirstByte 42.5 ms +10.35% -1.65% 46.6 ms +5.15% -1.07% -8.8%
largestContentfulPaint 92 ms +4.35% -4.35% 100 ms +4% -0% -8%
lcpMinusTtfb 46.7 ms +6.32% -1.28% 54 ms +2.22% -1.3% -13.52%
wpBeforeTemplate 26.22 ms +9.34% -2.4% 26.08 ms +4.14% -2.22% 0.54%
wpTemplate 13.56 ms +4.65% -1.4% 17.67 ms +0.68% -0.85% -23.26%
wpTotal 39.66 ms +10.56% -1.51% 43.62 ms +5.59% -1.03% -9.08%
wpMemoryUsage 6.01 MB +0% -0% 6.11 MB +0% -0% -1.66%
wpDbQueries 10 +0% -0% 14 +0% -0% -28.57%

media-processing

Metric 7ab5137 trunk % Change
mediaProcessingJpeg 396.68 ms +0.8% -0.47% 394.54 ms +1.01% -1.06% 0.54%
mediaProcessingAvif 6027.31 ms +0.29% -0.04% 6038.8 ms +0.12% -0.24% -0.19%
mediaProcessingJpegToAvif 4155.26 ms +0.22% -0.08% 4185.36 ms +0.51% -0.72% -0.72%

media-upload

Metric 7ab5137 trunk % Change
jpegUploadProcessing 1443.27 ms +34.27% -1.7% 1405.35 ms +0.52% -0.52% 2.7%
pngUploadProcessing 206.49 ms +6.13% -2.76% 207.03 ms +8.48% -4.15% -0.26%
largeJpegUploadProcessing 1406.32 ms +0.72% -0.33% 1400.48 ms +1.38% -0.75% 0.42%
multipleImageUploadProcessing 1559.77 ms +0.8% -1.01% 1568.77 ms +9.47% -1.84% -0.57%

post-editor

Metric 7ab5137 trunk % Change
serverResponse 500.99 ms +6.56% -5.95% 498.89 ms +1.76% -3.66% 0.42%
firstPaint 267.03 ms +24.53% -25.36% 241.98 ms +26.64% -22.25% 10.35%
domContentLoaded 1094.93 ms +2.24% -1.33% 1074.6 ms +0.99% -0.79% 1.89%
loaded 1096.27 ms +2.23% -1.34% 1075.99 ms +0.97% -0.79% 1.88%
firstContentfulPaint 455.4 ms +0.75% -3.55% 439.74 ms +0.92% -1.97% 3.56%
firstBlock 3264.83 ms +1.41% -0.62% 3199.65 ms +1.95% -0.67% 2.04%
type 19.93 ms +4.82% -3.36% 19.57 ms +6.75% -7.82% 1.84%
typeWithoutInspector 20.65 ms +6.1% -9.15% 18.55 ms +3.77% -2.32% 11.32%
typeWithTopToolbar 26.09 ms +3.76% -9.93% 23.37 ms +6.25% -4.19% 11.64%
typeContainer 8.66 ms +2.19% -7.27% 9.02 ms +3.99% -5.76% -3.99%
focus 71.95 ms +10.19% -2% 74.97 ms +4.47% -4.27% -4.03%
firstFocus 205.09 ms +0% -0% 190.33 ms +0% -0% 7.75%
selectAll 516.25 ms +3.17% -2.96% 532.14 ms +2.44% -6.62% -2.99%
listViewOpen 73.32 ms +4.23% -6.51% 69.21 ms +9.68% -8.57% 5.94%
inserterOpen 23.77 ms +14.72% -3.11% 23.41 ms +3.12% -3.84% 1.54%
inserterHover 2.98 ms +10.07% -6.38% 2.82 ms +8.16% -7.09% 5.67%
inserterSearch 8.34 ms +8.87% -14.75% 8.06 ms +8.31% -4.47% 3.47%
loadPatterns 641.52 ms +2.57% -2.89% 641.76 ms +2.47% -2.65% -0.04%
wpTotal 490.97 ms +6.25% -5.96% 488.8 ms +1.91% -3.68% 0.44%
wpMemoryUsage 13.04 MB +0% -0% 13.01 MB +0% -0% 0.28%
wpDbQueries 54 +0% -1.85% 54 +0% -0% 0%

site-editor

Metric 7ab5137 trunk % Change
serverResponse 500 ms +4.45% -1.17% 488.17 ms +2.22% -6.36% 2.42%
firstPaint 233.63 ms +7.74% -4.37% 280.98 ms +15.34% -6.22% -16.85%
domContentLoaded 1144.52 ms +0.76% -2.44% 1133.38 ms +1.17% -1.23% 0.98%
loaded 1145.68 ms +0.77% -2.43% 1134.56 ms +1.19% -1.25% 0.98%
firstContentfulPaint 440.72 ms +3.33% -1.35% 451.15 ms +1.08% -2.48% -2.31%
firstBlock 4159.02 ms +0.77% -0.35% 4153.27 ms +0.48% -0.54% 0.14%
type 20.2 ms +6.58% -5.84% 20.62 ms +3.25% -3.88% -2.04%
navigate 123.59 ms +15.37% -9.17% 120.22 ms +9.23% -4.92% 2.8%
loadPatterns 1231.93 ms +7.73% -0.64% 1291.18 ms +7.82% -14.07% -4.59%
loadPages 1071.87 ms +2.8% -0.67% 1065.07 ms +1.9% -1.47% 0.64%
wpTotal 490.24 ms +4.64% -1.25% 478.11 ms +2.43% -6.48% 2.54%
wpMemoryUsage 12.01 MB +0% -0% 11.97 MB +0% -0% 0.31%
wpDbQueries 43.5 +1.15% -1.15% 43.5 +1.15% -1.15% 0%

e5282f1 Run

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[Feature] Dashboard WordPress admin dashboard, widget framework, and layout customization Internationalization (i18n) Issues or PRs related to internationalization efforts [Type] Enhancement A suggestion for improvement.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Dashboard widgets: widget.json metadata strings never reach a translation catalog

4 participants