Why WordPress Demands “مخطّط المستند” Over Legacy Translations
In software localization, a string in isolation is a trap. When translating a massive platform like WordPress, looking at a spreadsheet of isolated English phrases often leads to “safe” but clunky translations. The ultimate source of truth is never the glossary—it is the source code.
For years, the Arabic localization for “Document Outline” has been ملخص عناوين المستند (literally: Summary of document headings). Born from an era where translators felt the need to heavily explain UI features to users (a process called explicitation), this string is wordy, descriptive, and ultimately outdated.

As we look toward modern WordPress UI paradigms, it is time to standardize this string to مخطّط المستند. To understand exactly why this update is necessary, we don’t need to debate linguistics—we just need to look at the code.
The Reference Code: A Window into the UI

Let’s examine the exact file where this string lives in the Gutenberg block editor: wp-includes/js/dist/editor.js, specifically within the TableOfContentsPanel component.
Here is the structural blueprint of that panel:
JavaScript
// ... [Lines 49560 - 49617 omitted for brevity] ...
<div className="table-of-contents__wrapper" role="note" aria-label={__("Document Statistics")}>
{/* Renders Counts: Words, Characters, Time to read, Headings, Paragraphs, Blocks */}
</div>
{ headingCount > 0 && (
<>
<hr />
<h2 className="table-of-contents__title">{__("Document Outline")}</h2>
<DocumentOutline
onSelect={onRequestClose}
hasOutlineItemsDisabled={hasOutlineItemsDisabled}
/>
</>
)}
// ... [Line 49630] ...
By reading this snippet, the context transforms the way we must approach the translation. Here is how the reference code guides us to a vastly superior Arabic localization.
1. The Code Proves It’s a Structure, Not a “Summary”
Look at the logic in the code. The panel is divided into two distinct sections. The top half is strictly for Document Statistics (Words, Characters, reading time). This top section acts as the actual summary of the document’s contents.
Below the <hr /> (horizontal rule), we see the Document Outline. If we keep the legacy translation ملخص عناوين المستند (Summary of headings), we create a semantic clash. We are placing a “summary” directly underneath actual statistical summaries.
The <DocumentOutline/> component rendered here is a navigational tree—a structural skeleton that lets users jump between header blocks. مخطّط means “plan,” “map,” or “outline.” By using مخطّط المستند, we accurately tell the user they are looking at a structural map, differentiating it cleanly from the statistics above it.
2. The Original File Path Reveals Architectural Intent While the bundled distribution code lives in editor.js, line 49560 provides a crucial breadcrumb to the original, uncompiled source code: // packages/editor/build-module/components/table-of-contents/panel.mjs.

This file path is a L10n goldmine. It explicitly identifies that this UI element belongs to the table-of-contents component. A Table of Contents is inherently a navigational map of a document’s hierarchy; it is never a summary of the text itself. By organizing the code under table-of-contents, the core engineering team is signaling clear structural intent.
Translating this feature as a ملخص (summary) directly contradicts the architectural blueprint of the software. Conversely, مخطّط (outline/map) perfectly echoes the navigational purpose of a Table of Contents, ensuring the Arabic string aligns with the foundational logic of the Gutenberg editor.
3. The <h2> Tag Demands Brevity
Notice the HTML element wrapping our string:
<h2 className="table-of-contents__title">{__("Document Outline")}</h2>
This string is not explanatory text; it is a section heading (<h2>). In UI design, headings must be punchy, scannable, and instantly recognizable.
- Legacy:
ملخص عناوين المستند(3 words, visually heavy) - Proposed:
مخطّط المستند(2 words, crisp and standard)
Users do not read software interfaces; they scan them. A three-word, overly descriptive heading slows down the user’s cognitive parsing. مخطّط المستند functions perfectly as a quick, scannable title.
4. Spatial Constraints of the Sidebar Panel
The component name is TableOfContentsPanel. In the WordPress editor, this panel is a narrow sidebar or a popover menu. UI real estate is highly restricted.
When a multi-word string like ملخص عناوين المستند is crammed into a narrow sidebar, it risks truncation (e.g., ملخص عناوين ا...) or awkward line breaks, especially on mobile views. The source code reveals the physical constraints of the UI, proving that the shorter, more compact مخطّط المستند is a functional necessity to preserve the design layout.
5. Aligning with Industry Standards
As localization specialists, consistency across the digital ecosystem is one of our primary goals. When users switch between Microsoft Word, Google Docs, Apple Pages, and various web-based CMS platforms, they shouldn’t have to learn a new vocabulary for the exact same tool.
Major tech giants have already recognized the need for concise, structural terminology:
- Google Docs currently utilizes
مخطّط المستندfor its outline feature. - Microsoft Word uses similar structural terminology, like
جزء التنقل(Navigation Pane) orمخطط المستند(Document Map in older versions).
By updating to مخطّط المستند, we align our product with the established mental models of millions of Arab users. We stop forcing them to translate our unique legacy jargon and instead speak the language they already know.
Conclusion: Translating for the Future
WordPress is a constantly evolving ecosystem. With modern iterations of the block editor, the UI is becoming cleaner, faster, and more minimalist. Our Arabic localization must evolve with it.
Relying on the source code changes a translator from a mere linguist into a UI/UX advocate. The code at editor.js:49618 explicitly tells us that “Document Outline” is a compact, structural heading housed within a narrow panel. By dropping the outdated, hand-holding explicitation, observing UI boundaries, and adopting the industry standard مخطّط المستند, we respect the developer’s design and ultimately provide a more native, professional experience for the Arab WordPress user.

