Open Source • Professional

Fixed Missing Block Translations

Fixing i18n for Inner Blocks in Cart & Checkout Editor

Fixed an internationalization bug preventing Inner Block titles and descriptions from translating correctly in the WordPress editor inspector. (Skills: PHP, JS, WordPress i18n)

WordPress
PHP
JavaScript
Gutenberg
i18n

Discuss this project View Contribution

WooCommerce Block Editor after translations are fixed — Editor inspector panels now correctly display translations for Inner Block titles and descriptions.

Context

Solving Internationalization Gaps in the Block Editor

Why this work mattered and the environment it lived in.

Within the WooCommerce Blocks editor experience—especially for Cart & Checkout blocks—certain "Inner Blocks" (such as components for title and description) suffered from a critical internationalization issue. When these blocks were registered only on the client-side (JavaScript), translatable properties like title and description were not appearing translated in the editor inspector panel, even though translation files existed. This led to poor experience for non-English users configuring stores in the block editor.

Full background

Investigation revealed that although translations were present in .po files (typically used for server-side translation), registering blocks purely via JavaScript meant those translations weren't loaded for the inspector UI. This surfaced a gap in how WordPress/Gutenberg manages block internationalization, especially for client-only registration.

Snapshot

Highlights, Challenges, Skills

A concise readout for quick evaluators.

Highlights

Authored the fix that delivered proper translation support for all Inner Blocks in WooCommerce Blocks' editor UI
Aligned implementation with latest WordPress and Gutenberg recommended practices
Diagnosed and solved a long-standing i18n issue across PHP and JavaScript boundaries

Challenges

Deep-diving into WordPress and Gutenberg block i18n internals
Refactoring registration patterns to work server-side and maintain full JS functionality
Balancing code cleanliness (via AbstractInnerBlock) with upgrade safety and existing functionality

Skills Demonstrated

WordPress Block Editor (Gutenberg) APIs: server and client registration
Internationalization (i18n) debugging and implementation
PHP: Writing server-side logic and registration patterns

Role

My Role & Contributions

As the author of the solution (PR #6737), I analyzed the i18n system, refactored the registration approach, and delivered a robust architecture aligned with WordPress block development best practices.

Problem Analysis: Pinpointed the disconnect between client- and server-side block registration and how it impacted translation delivery
Solution Strategy: Shifted Inner Block registration to the server side, leveraging block.json metadata to mark fields as translatable
Implementation:
- Generated block.json files for all affected Inner Blocks, marking properties (title, description, keywords) as translatable
- Registered blocks server-side using PHP's register_block_type and the new metadata files
- Introduced an AbstractInnerBlock PHP class to consolidate server-side registration, purposefully omitting editor_script for proper script handling
- Ensured only minimal client-side settings are still registered in JS for block runtime behavior

Key Contributions

Features & Outcomes

Open narratives that explain the impact of each slice of work.

Contribution 01

Server-Side Block Registration via block.json

Leverages WordPress best practices for i18n in custom blocks

Transitioned registration of Inner Blocks from client-side JS to server-side PHP using block.json metadata. By marking appropriate fields as translatable, the editor's inspector panel now receives and displays the correct translations, as loaded from .po files via standard WordPress localization mechanisms.

This approach matches modern WordPress guidelines and guarantees translation support, regardless of plugin or theme localization state.

Implemented and tested for all Cart & Checkout Inner Blocks
Used AbstractInnerBlock PHP class to minimize code duplication

See WordPress docs on block.json best practices for context.

Editor Inspector after translation fix — After: Inner Block titles/descriptions properly localized

Contribution 02

Internationalization Debugging & Problem Solving

Diagnosed and resolved complex block i18n issue

Investigated why translations defined in .po files and expected via standard Gutenberg processes were not loaded for Inner Blocks, even when site language and translation files were present. Discovered that pure client-side registration does not suffice for editor UI translation fields.

Traced translation loading paths across PHP and JavaScript
Verified resolved behavior via inspector UI tests in multiple languages
Documented registration changes for future block development

Technical Deep Dive

Technical Implementation

Block Registration:

Generated block.json files for all affected Inner Blocks (title, description, keywords marked as translatable)
Refactored block registration to use PHP's register_block_type, following WordPress guidance
Introduced an AbstractInnerBlock class to consolidate server-side logic and avoid extraneous editor_script loading

Internationalization:

Ensured translations are loaded from .po files and available to the editor UI
Reduced time to translation correctness for all supported languages in Cart & Checkout blocks

Languages & Frameworks:

WordPress PHP, JavaScript (ESNext), block.json, Gutenberg block editor

Testing:

Verified translation loading in various language environments (using WP site language switch, .po/mo files)
Regression tested block editor UI to confirm zero-impact on English users

Growth

Key Learnings

Applied best practices for WordPress block development with full i18n support
Gained deeper insight into server- vs. client-side registration implications
Reinforced importance of block.json metadata for modern block development
Improved processes for triaging and resolving language-specific bugs in editor UI

Toolkit

Technologies Used

Core Stack

WordPress
PHP
JavaScript
Gutenberg Blocks
block.json

Libraries

WooCommerce Blocks
@wordpress/scripts
@wordpress/block-editor
@wordpress/i18n
@wordpress/components

Tools

GitHub
WordPress Local Environment
Poedit / .po/.mo files
VSCode

← Back to All Projects Contact Me