From f65288ef6cd7ee7e2b8eb1c8f042d9aca3d7f04c Mon Sep 17 00:00:00 2001 From: Claas Augner Date: Fri, 20 Mar 2026 11:38:46 +0100 Subject: [PATCH 1/5] feat(menu): introduce `tabs.js` and `l10n.js` to localize menu strings - `tabs.js` enriches `tabs.json` with l10n IDs generated from the text. - `l10n.js` derives a strings Map for the extractor --- components/menu/l10n.js | 39 ++++++++++++++++++++++++ components/menu/tabs.js | 61 ++++++++++++++++++++++++++++++++++++++ components/menu/types.d.ts | 12 ++++++-- 3 files changed, 110 insertions(+), 2 deletions(-) create mode 100644 components/menu/l10n.js create mode 100644 components/menu/tabs.js diff --git a/components/menu/l10n.js b/components/menu/l10n.js new file mode 100644 index 000000000..debb40dcb --- /dev/null +++ b/components/menu/l10n.js @@ -0,0 +1,39 @@ +import { TABS } from "./tabs.js"; + +/** + * All localizable menu strings, derived from tabs.js. + * Used by the l10n extractor only — not imported at runtime. + * + * @type {Map} + */ +export const strings = new Map( + TABS.flatMap((tab) => { + /** @type {[string, string][]} */ + const entries = []; + + if (typeof tab.buttonL10nId === "string") { + entries.push([tab.buttonL10nId, /** @type {string} */ (tab.buttonText)]); + } else { + entries.push([tab.buttonL10nId.long, tab.buttonText.long], [tab.buttonL10nId.short, tab.buttonText.short]); + } + + if (!("panelTitle" in tab)) return entries; + + entries.push([tab.panelTitle.l10nId, tab.panelTitle.text]); + + for (const group of tab.panelGroups) { + if (group.titleL10nId) { + entries.push([group.titleL10nId, /** @type {string} */ (group.title)]); + } + for (const item of group.items) { + if (!("l10nId" in item)) continue; + entries.push([item.l10nId, item.text]); + if (item.labelL10nId) { + entries.push([item.labelL10nId, /** @type {string} */ (item.label)]); + } + } + } + + return entries; + }), +); diff --git a/components/menu/tabs.js b/components/menu/tabs.js new file mode 100644 index 000000000..e5dadc3fe --- /dev/null +++ b/components/menu/tabs.js @@ -0,0 +1,61 @@ +import tabsData from "./tabs.json" with { type: "json" }; + +/** + * Converts a string to a kebab-case slug for use in l10n IDs. + * @param {string} str + */ +const slugify = (str) => + str + .toLowerCase() + .replaceAll(/[^\p{L}\p{N}]+/gu, "-") + .replaceAll(/^-|-$/g, ""); + +/** + * Menu tabs enriched with l10n IDs. + * + * @type {ReadonlyArray} + */ +export const TABS = Object.freeze( + /** @type {import("./types.js").MenuTab[]} */ ( + tabsData.map((tab) => { + const buttonL10nId = + typeof tab.buttonText === "string" + ? `menu-${tab.id}` + : { + long: `menu-${tab.id}`, + short: `menu-${tab.id}-short`, + }; + + if (!("panelTitle" in tab)) { + return { ...tab, buttonL10nId }; + } + + return { + ...tab, + buttonL10nId, + panelTitle: { + ...tab.panelTitle, + l10nId: `menu-${tab.id}-panel-title`, + }, + panelGroups: tab.panelGroups.map((group, gi) => { + const groupSlug = group.title ? slugify(group.title) : String(gi); + return { + ...group, + titleL10nId: group.title + ? `menu-${tab.id}-${groupSlug}` + : undefined, + items: group.items.map((item) => { + if ("render" in item) return item; + const l10nId = `menu-${tab.id}-${groupSlug}-${slugify(item.text)}`; + return { + ...item, + l10nId, + labelL10nId: item.label ? `${l10nId}-label` : undefined, + }; + }), + }; + }), + }; + }) + ), +); diff --git a/components/menu/types.d.ts b/components/menu/types.d.ts index 877a48713..24a2176f5 100644 --- a/components/menu/types.d.ts +++ b/components/menu/types.d.ts @@ -1,19 +1,25 @@ import { ServerRenderedTemplate } from "@lit-labs/ssr"; + +type ButtonText = string | { long: string; short: string }; +type ButtonL10nId = string | { long: string; short: string }; + interface BaseTab { id: string; buttonText: ButtonText; + buttonL10nId: ButtonL10nId; } -type ButtonText = string | { long: string; short: string }; - interface PanelTitle { text: string; slug?: string; + l10nId: string; } interface BaseItem { text: string; label?: string; + l10nId: string; + labelL10nId?: string; } interface SlugItem extends BaseItem { @@ -35,6 +41,7 @@ type PanelItem = LinkItem | RenderItem; interface PanelGroup { title?: string; + titleL10nId?: string; items: PanelItem[]; } @@ -45,6 +52,7 @@ interface DropdownTab extends BaseTab { interface LinkTab extends BaseTab { href: string; + buttonL10nId: string; } export type MenuTab = DropdownTab | LinkTab; From 22d14779ce51c15a46cfe85dd09b27492c204c9e Mon Sep 17 00:00:00 2001 From: Claas Augner Date: Fri, 20 Mar 2026 11:39:02 +0100 Subject: [PATCH 2/5] refactor(menu): consume tabs via `tabs.js` --- components/menu/constants.js | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/components/menu/constants.js b/components/menu/constants.js index 995280c23..12647497b 100644 --- a/components/menu/constants.js +++ b/components/menu/constants.js @@ -1,8 +1,6 @@ import missingDocs from "./missing-docs.json" with { type: "json" }; -import tabs from "./tabs.json" with { type: "json" }; -/** @type {Readonly}*/ -export const TABS = Object.freeze(tabs); +export { TABS } from "./tabs.js"; /** * Lists untranslated menu pages per locale. From ecd6bfd7b58748758b9c5dc1ce81ee579e156977 Mon Sep 17 00:00:00 2001 From: Claas Augner Date: Fri, 20 Mar 2026 11:41:59 +0100 Subject: [PATCH 3/5] feat(menu): localize text --- components/menu/l10n.js | 12 ++++++--- components/menu/server.js | 54 ++++++++++++++++++++++++-------------- components/menu/tabs.js | 9 ++++--- components/menu/types.d.ts | 21 +++++++++++++++ 4 files changed, 71 insertions(+), 25 deletions(-) diff --git a/components/menu/l10n.js b/components/menu/l10n.js index debb40dcb..90fad59f0 100644 --- a/components/menu/l10n.js +++ b/components/menu/l10n.js @@ -11,10 +11,16 @@ export const strings = new Map( /** @type {[string, string][]} */ const entries = []; - if (typeof tab.buttonL10nId === "string") { - entries.push([tab.buttonL10nId, /** @type {string} */ (tab.buttonText)]); + if (typeof tab.buttonText === "string") { + entries.push([/** @type {string} */ (tab.buttonL10nId), tab.buttonText]); } else { - entries.push([tab.buttonL10nId.long, tab.buttonText.long], [tab.buttonL10nId.short, tab.buttonText.short]); + const buttonL10nId = /** @type {{ long: string; short: string }} */ ( + tab.buttonL10nId + ); + entries.push( + [buttonL10nId.long, tab.buttonText.long], + [buttonL10nId.short, tab.buttonText.short], + ); } if (!("panelTitle" in tab)) return entries; diff --git a/components/menu/server.js b/components/menu/server.js index fb4cc6a05..02dc9b848 100644 --- a/components/menu/server.js +++ b/components/menu/server.js @@ -33,9 +33,9 @@ export class Menu extends ServerComponent { * Renders a link to a page. * * @param {string} slug - The link slug (the part after `/en-US/docs/`!). - * @param {string} text - The link text. + * @param {import("../../types/fluent.js").L10nTag} text - The link text. * @param {object} [options] - * @param {string} [options.label] - The title and aria-label of the link. + * @param {import("../../types/fluent.js").L10nTag} [options.label] - The title and aria-label of the link. * @param {boolean} [options.primary] - Whether this is the primary link (in the panel title). */ const link = (slug, text, { label, primary = false } = {}) => { @@ -69,27 +69,29 @@ export class Menu extends ServerComponent { class="menu__tab-link" href=${tab.href} data-glean-id=${`menu_click_link: top-level -> ${tab.href}`} - >${tab.buttonText}${context.l10n(tab.buttonL10nId)}` : html`

${tab.panelTitle.slug - ? link(tab.panelTitle.slug, tab.panelTitle.text, { - primary: true, - }) - : tab.panelTitle.text} + ? link( + tab.panelTitle.slug, + context.l10n(tab.panelTitle.l10nId), + { primary: true }, + ) + : context.l10n(tab.panelTitle.l10nId)}

${tab.panelGroups.map((group) => { @@ -100,9 +102,15 @@ export class Menu extends ServerComponent { ${"render" in item ? item.render() : "slug" in item - ? link(item.slug, item.text, { - label: item.label, - }) + ? link( + item.slug, + context.l10n(item.l10nId), + { + label: item.labelL10nId + ? context.l10n(item.labelL10nId) + : undefined, + }, + ) : html`${item.text}${context.l10n(item.l10nId)}`} `, )} `; - return "title" in group + return group.titleL10nId ? html`
-
${group.title}
+
${context.l10n(group.titleL10nId)}
${items}
` : items; diff --git a/components/menu/tabs.js b/components/menu/tabs.js index e5dadc3fe..bf7e14772 100644 --- a/components/menu/tabs.js +++ b/components/menu/tabs.js @@ -1,4 +1,7 @@ -import tabsData from "./tabs.json" with { type: "json" }; +import tabsDataRaw from "./tabs.json" with { type: "json" }; + +/** @type {Readonly} */ +const RAW_TABS = Object.freeze(tabsDataRaw); /** * Converts a string to a kebab-case slug for use in l10n IDs. @@ -17,7 +20,7 @@ const slugify = (str) => */ export const TABS = Object.freeze( /** @type {import("./types.js").MenuTab[]} */ ( - tabsData.map((tab) => { + RAW_TABS.map((tab) => { const buttonL10nId = typeof tab.buttonText === "string" ? `menu-${tab.id}` @@ -37,7 +40,7 @@ export const TABS = Object.freeze( ...tab.panelTitle, l10nId: `menu-${tab.id}-panel-title`, }, - panelGroups: tab.panelGroups.map((group, gi) => { + panelGroups: (tab.panelGroups ?? []).map((group, gi) => { const groupSlug = group.title ? slugify(group.title) : String(gi); return { ...group, diff --git a/components/menu/types.d.ts b/components/menu/types.d.ts index 24a2176f5..323110a6b 100644 --- a/components/menu/types.d.ts +++ b/components/menu/types.d.ts @@ -1,5 +1,26 @@ import { ServerRenderedTemplate } from "@lit-labs/ssr"; +export interface RawItem { + text: string; + label?: string; + slug?: string; + href?: string; + icon?: string; +} + +export interface RawGroup { + title?: string; + items: RawItem[]; +} + +export interface RawTab { + id: string; + buttonText: string | { long: string; short: string }; + href?: string; + panelTitle?: { text: string; slug?: string }; + panelGroups?: RawGroup[]; +} + type ButtonText = string | { long: string; short: string }; type ButtonL10nId = string | { long: string; short: string }; From d8c4fb3c47222d4318384a9b46756d526967fb2f Mon Sep 17 00:00:00 2001 From: Claas Augner Date: Fri, 20 Mar 2026 11:42:39 +0100 Subject: [PATCH 4/5] feat(l10n): extract strings from `components/**/l10n.js` --- l10n/parser/extractor.js | 41 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 39 insertions(+), 2 deletions(-) diff --git a/l10n/parser/extractor.js b/l10n/parser/extractor.js index 706788e1a..9dfd327f7 100644 --- a/l10n/parser/extractor.js +++ b/l10n/parser/extractor.js @@ -1,8 +1,8 @@ -import { readFile, writeFile } from "node:fs/promises"; +import { glob, readFile, writeFile } from "node:fs/promises"; import path from "node:path"; -import { fileURLToPath } from "node:url"; +import { fileURLToPath, pathToFileURL } from "node:url"; import { Comment, @@ -48,6 +48,33 @@ export async function extract(options = {}) { } } +/** + * Imports all `l10n.js` modules under the components directory and merges + * their exported `strings` Maps into a single Map. + * + * @param {string} componentsDir + * @returns {Promise>} + */ +async function scrapeL10nModules(componentsDir) { + /** @type {Map} */ + const map = new Map(); + for await (const file of glob("**/l10n.js", { cwd: componentsDir })) { + const { strings } = await import( + pathToFileURL(path.join(componentsDir, file)).href + ); + if (!(strings instanceof Map)) continue; + for (const [id, value] of strings) { + if (map.has(id) && map.get(id) !== value) { + throw new Error( + `L10n extractor: \`${id}\` is a duplicate id with different text`, + ); + } + map.set(id, value); + } + } + return map; +} + /** * @param {string} manualEntryPath * @param {string} scrapeGlob @@ -56,6 +83,16 @@ export async function createFluentResource(manualEntryPath, scrapeGlob) { const manualEntries = await getManualEntries(manualEntryPath); const tags = scrapeL10nTags(scrapeGlob); + const componentsDir = path.join(__dirname, "..", "..", "components"); + for (const [id, value] of await scrapeL10nModules(componentsDir)) { + if (tags.has(id) && tags.get(id) !== value) { + throw new Error( + `L10n extractor: \`${id}\` is a duplicate id with different text`, + ); + } + tags.set(id, value); + } + return new Resource([ new Comment(TEMPLATE_HEADER), ...manualEntries.filter((entry) => { From a06ffbb0c82430685a620ec27d256fdf17b8f3b2 Mon Sep 17 00:00:00 2001 From: Claas Augner Date: Fri, 20 Mar 2026 11:43:26 +0100 Subject: [PATCH 5/5] chore(l10n): run `npm run l10n` --- l10n/template.ftl | 121 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 121 insertions(+) diff --git a/l10n/template.ftl b/l10n/template.ftl index 5863e64a6..e6da41fa8 100644 --- a/l10n/template.ftl +++ b/l10n/template.ftl @@ -318,3 +318,124 @@ user-menu-feedback = Feedback user-menu-user = User writer-open-editor-open-in-editor = Open in editor writer-toolbar-view-on-mdn = View on MDN +menu-html = HTML +menu-html-panel-title = HTML: Markup language +menu-html-html-reference = HTML reference +menu-html-html-reference-elements = Elements +menu-html-html-reference-global-attributes = Global attributes +menu-html-html-reference-attributes = Attributes +menu-html-html-reference-see-all = See all… +menu-html-html-reference-see-all-label = See all HTML references +menu-html-html-guides = HTML guides +menu-html-html-guides-responsive-images = Responsive images +menu-html-html-guides-html-cheatsheet = HTML cheatsheet +menu-html-html-guides-date-time-formats = Date & time formats +menu-html-html-guides-see-all = See all… +menu-html-html-guides-see-all-label = See all HTML guides +menu-html-markup-languages = Markup languages +menu-html-markup-languages-svg = SVG +menu-html-markup-languages-mathml = MathML +menu-html-markup-languages-xml = XML +menu-css = CSS +menu-css-panel-title = CSS: Styling language +menu-css-css-reference = CSS reference +menu-css-css-reference-properties = Properties +menu-css-css-reference-selectors = Selectors +menu-css-css-reference-at-rules = At-rules +menu-css-css-reference-values = Values +menu-css-css-reference-see-all = See all… +menu-css-css-reference-see-all-label = See all CSS references +menu-css-css-guides = CSS guides +menu-css-css-guides-box-model = Box model +menu-css-css-guides-animations = Animations +menu-css-css-guides-flexbox = Flexbox +menu-css-css-guides-colors = Colors +menu-css-css-guides-see-all = See all… +menu-css-css-guides-see-all-label = See all CSS guides +menu-css-layout-cookbook = Layout cookbook +menu-css-layout-cookbook-column-layouts = Column layouts +menu-css-layout-cookbook-centering-an-element = Centering an element +menu-css-layout-cookbook-card-component = Card component +menu-css-layout-cookbook-see-all = See all… +menu-javascript = JavaScript +menu-javascript-short = JS +menu-javascript-panel-title = JavaScript: Scripting language +menu-javascript-js-reference = JS reference +menu-javascript-js-reference-standard-built-in-objects = Standard built-in objects +menu-javascript-js-reference-expressions-operators = Expressions & operators +menu-javascript-js-reference-statements-declarations = Statements & declarations +menu-javascript-js-reference-functions = Functions +menu-javascript-js-reference-see-all = See all… +menu-javascript-js-reference-see-all-label = See all JavaScript references +menu-javascript-js-guides = JS guides +menu-javascript-js-guides-control-flow-error-handing = Control flow & error handing +menu-javascript-js-guides-loops-and-iteration = Loops and iteration +menu-javascript-js-guides-working-with-objects = Working with objects +menu-javascript-js-guides-using-classes = Using classes +menu-javascript-js-guides-see-all = See all… +menu-javascript-js-guides-see-all-label = See all JavaScript guides +menu-webapis = Web APIs +menu-webapis-panel-title = Web APIs: Programming interfaces +menu-webapis-web-api-reference = Web API reference +menu-webapis-web-api-reference-file-system-api = File system API +menu-webapis-web-api-reference-fetch-api = Fetch API +menu-webapis-web-api-reference-geolocation-api = Geolocation API +menu-webapis-web-api-reference-html-dom-api = HTML DOM API +menu-webapis-web-api-reference-push-api = Push API +menu-webapis-web-api-reference-service-worker-api = Service worker API +menu-webapis-web-api-reference-see-all = See all… +menu-webapis-web-api-reference-see-all-label = See all Web API guides +menu-webapis-web-api-guides = Web API guides +menu-webapis-web-api-guides-using-the-web-animation-api = Using the Web animation API +menu-webapis-web-api-guides-using-the-fetch-api = Using the Fetch API +menu-webapis-web-api-guides-working-with-the-history-api = Working with the History API +menu-webapis-web-api-guides-using-the-web-speech-api = Using the Web speech API +menu-webapis-web-api-guides-using-web-workers = Using web workers +menu-all = All +menu-all-panel-title = All web technology +menu-all-technologies = Technologies +menu-all-technologies-accessibility = Accessibility +menu-all-technologies-http = HTTP +menu-all-technologies-uri = URI +menu-all-technologies-web-extensions = Web extensions +menu-all-technologies-webassembly = WebAssembly +menu-all-technologies-webdriver = WebDriver +menu-all-technologies-see-all = See all… +menu-all-technologies-see-all-label = See all web technology references +menu-all-topics = Topics +menu-all-topics-media = Media +menu-all-topics-performance = Performance +menu-all-topics-privacy = Privacy +menu-all-topics-security = Security +menu-all-topics-progressive-web-apps = Progressive web apps +menu-learn = Learn +menu-learn-panel-title = Learn web development +menu-learn-frontend-developer-course = Frontend developer course +menu-learn-frontend-developer-course-getting-started-modules = Getting started modules +menu-learn-frontend-developer-course-core-modules = Core modules +menu-learn-frontend-developer-course-mdn-curriculum = MDN Curriculum +menu-learn-frontend-developer-course-check-out-the-video-course-from-scrimba-our-partner = Check out the video course from Scrimba, our partner +menu-learn-learn-html = Learn HTML +menu-learn-learn-html-structuring-content-with-html-module = Structuring content with HTML module +menu-learn-learn-css = Learn CSS +menu-learn-learn-css-css-styling-basics-module = CSS styling basics module +menu-learn-learn-css-css-layout-module = CSS layout module +menu-learn-learn-javascript = Learn JavaScript +menu-learn-learn-javascript-dynamic-scripting-with-javascript-module = Dynamic scripting with JavaScript module +menu-tools = Tools +menu-tools-panel-title = Discover our tools +menu-tools-0-playground = Playground +menu-tools-0-http-observatory = HTTP Observatory +menu-tools-1-border-image-generator = Border-image generator +menu-tools-1-border-radius-generator = Border-radius generator +menu-tools-1-box-shadow-generator = Box-shadow generator +menu-tools-1-color-format-converter = Color format converter +menu-tools-1-color-mixer = Color mixer +menu-tools-1-shape-generator = Shape generator +menu-about = About +menu-about-panel-title = Get to know MDN better +menu-about-0-about-mdn = About MDN +menu-about-0-advertise-with-us = Advertise with us +menu-about-1-community = Community +menu-about-1-mdn-on-github = MDN on GitHub +menu-blog = Blog