feat(menu): support entry localization

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<import("./types.js").MenuTab[]>}*/
-export const TABS = Object.freeze(tabs);
+export { TABS } from "./tabs.js";
 
 /**
  * Lists untranslated menu pages per locale.

components/menu/l10n.js

@@ -0,0 +1,45 @@
+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<string, string>}
+ */
+export const strings = new Map(
+  TABS.flatMap((tab) => {
+    /** @type {[string, string][]} */
+    const entries = [];
+
+    if (typeof tab.buttonText === "string") {
+      entries.push([/** @type {string} */ (tab.buttonL10nId), tab.buttonText]);
+    } else {
+      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;
+
+    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;
+  }),
+);

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}</a
+                  >${context.l10n(tab.buttonL10nId)}</a
                 >`
               : html`<mdn-dropdown>
                   <button class="menu__tab-button" type="button" slot="button">
-                    ${typeof tab.buttonText === "string"
+                    ${typeof tab.buttonL10nId === "string"
                       ? html`<span class="menu__tab-label"
-                          >${tab.buttonText}</span
+                          >${context.l10n(tab.buttonL10nId)}</span
                         >`
                       : html`<span class="menu__tab-label" data-type="long"
-                            >${tab.buttonText.long}</span
+                            >${context.l10n(tab.buttonL10nId.long)}</span
                           ><span class="menu__tab-label" data-type="short"
-                            >${tab.buttonText.short}</span
+                            >${context.l10n(tab.buttonL10nId.short)}</span
                           >`}
                   </button>
                   <div class="menu__panel" slot="dropdown">
                     <p class="menu__panel-title">
                       ${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)}
                     </p>
                     <div class="menu__panel-content">
                       ${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`<a
                                         class=${ifDefined(
                                           [
@@ -117,18 +125,26 @@ export class Menu extends ServerComponent {
                                         )}
                                         data-icon=${ifDefined(item.icon)}
                                         href=${item.href}
-                                        aria-label=${ifDefined(item.label)}
-                                        title=${ifDefined(item.label)}
+                                        aria-label=${ifDefined(
+                                          item.labelL10nId
+                                            ? context.l10n(item.labelL10nId)
+                                            : undefined,
+                                        )}
+                                        title=${ifDefined(
+                                          item.labelL10nId
+                                            ? context.l10n(item.labelL10nId)
+                                            : undefined,
+                                        )}
                                         data-glean-id=${gleanId(item.href)}
-                                        >${item.text}</a
+                                        >${context.l10n(item.l10nId)}</a
                                       >`}
                               </li>`,
                           )}
                         </ul>`;
 
-                        return "title" in group
+                        return group.titleL10nId
                           ? html`<dl>
-                              <dt>${group.title}</dt>
+                              <dt>${context.l10n(group.titleL10nId)}</dt>
                               <dd>${items}</dd>
                             </dl>`
                           : items;

components/menu/tabs.js

@@ -0,0 +1,64 @@
+import tabsDataRaw from "./tabs.json" with { type: "json" };
+
+/** @type {Readonly<import("./types.d.ts").RawTab[]>} */
+const RAW_TABS = Object.freeze(tabsDataRaw);
+
+/**
+ * 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<import("./types.js").MenuTab>}
+ */
+export const TABS = Object.freeze(
+  /** @type {import("./types.js").MenuTab[]} */ (
+    RAW_TABS.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,
+              };
+            }),
+          };
+        }),
+      };
+    })
+  ),
+);

components/menu/types.d.ts

@@ -1,19 +1,46 @@
 import { ServerRenderedTemplate } from "@lit-labs/ssr";
-interface BaseTab {
+
+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: ButtonText;
+  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 };
+
+interface BaseTab {
+  id: string;
+  buttonText: ButtonText;
+  buttonL10nId: ButtonL10nId;
+}
 
 interface PanelTitle {
   text: string;
   slug?: string;
+  l10nId: string;
 }
 
 interface BaseItem {
   text: string;
   label?: string;
+  l10nId: string;
+  labelL10nId?: string;
 }
 
 interface SlugItem extends BaseItem {
@@ -35,6 +62,7 @@ type PanelItem = LinkItem | RenderItem;
 
 interface PanelGroup {
   title?: string;
+  titleL10nId?: string;
   items: PanelItem[];
 }
 
@@ -45,6 +73,7 @@ interface DropdownTab extends BaseTab {
 
 interface LinkTab extends BaseTab {
   href: string;
+  buttonL10nId: string;
 }
 
 export type MenuTab = DropdownTab | LinkTab;

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<Map<string, string>>}
+ */
+async function scrapeL10nModules(componentsDir) {
+  /** @type {Map<string, string>} */
+  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) => {