chore(types): narrow string to Locale where possible (#11323)

Co-authored-by: Claas Augner <[email protected]>

build/blog.ts

@@ -36,6 +36,7 @@ import { HydrationData } from "../libs/types/hydration.js";
 import { DEFAULT_LOCALE } from "../libs/constants/index.js";
 import { memoize } from "../content/utils.js";
 import { buildSitemap } from "./sitemaps.js";
+import { type Locale } from "../libs/types/core.js";
 
 const READ_TIME_FILTER = /[\w<>.,!?]+/;
 const HIDDEN_CODE_BLOCK_MATCH = /```.*hidden[\s\S]*?```/g;
@@ -342,7 +343,7 @@ export async function buildBlogPosts(options: {
 export interface BlogPostDoc {
   url: string;
   rawBody: string;
-  metadata: BlogPostMetadata & { locale: string };
+  metadata: BlogPostMetadata & { locale: Locale };
   isMarkdown: true;
   fileInfo: {
     path: string;
@@ -383,7 +384,7 @@ export async function buildPost(
 
   doc.title = metadata.title || "";
   doc.mdn_url = document.url;
-  doc.locale = metadata.locale as string;
+  doc.locale = metadata.locale;
   doc.native = LANGUAGES_RAW[DEFAULT_LOCALE]?.native;
 
   if ($("math").length > 0) {

build/index.ts

@@ -373,7 +373,7 @@ export async function buildDocument(
 
   doc.title = metadata.title || "";
   doc.mdn_url = document.url;
-  doc.locale = metadata.locale as string;
+  doc.locale = metadata.locale;
   doc.native = LANGUAGES.get(doc.locale.toLowerCase())?.native;
 
   // metadata doesn't have a browser-compat key on translated docs:

build/spas.ts

@@ -27,6 +27,7 @@ import { findByURL } from "../content/document.js";
 import { buildDocument } from "./index.js";
 import { findPostBySlug } from "./blog.js";
 import { buildSitemap } from "./sitemaps.js";
+import { type Locale } from "../libs/types/core.js";
 import { HydrationData } from "../libs/types/hydration.js";
 
 const FEATURED_ARTICLES = [
@@ -45,7 +46,7 @@ const LATEST_NEWS: (NewsItem | string)[] = [
 const contributorSpotlightRoot = CONTRIBUTOR_SPOTLIGHT_ROOT;
 
 async function buildContributorSpotlight(
-  locale: string,
+  locale: Locale,
   options: { verbose?: boolean }
 ) {
   const prefix = "community/spotlight";
@@ -295,7 +296,7 @@ export async function buildSPAs(options: {
       continue;
     }
     for (const localeLC of fs.readdirSync(root)) {
-      const locale = VALID_LOCALES.get(localeLC) || localeLC;
+      const locale = VALID_LOCALES.get(localeLC) || (localeLC as Locale);
       if (!isValidLocale(locale)) {
         continue;
       }

content/document.ts

@@ -35,6 +35,7 @@ import {
 } from "./utils.js";
 import * as Redirect from "./redirect.js";
 import { DocFrontmatter, UnbuiltDocument } from "../libs/types/document.js";
+import { type Locale } from "../libs/types/core.js";
 
 export { urlToFolderPath, MEMOIZE_INVALIDATE } from "./utils.js";
 
@@ -195,7 +196,7 @@ export const read = memoize(
     let filePath: string = null;
     let folder: string = null;
     let root: string = null;
-    let locale: string = null;
+    let locale: Locale = null;
 
     if (fs.existsSync(folderOrFilePath)) {
       filePath = folderOrFilePath;

content/redirect.ts

@@ -6,6 +6,7 @@ import { decodePath, slugToFolder } from "../libs/slug-utils/index.js";
 import { CONTENT_ROOT, CONTENT_TRANSLATED_ROOT } from "../libs/env/index.js";
 import { VALID_LOCALES } from "../libs/constants/index.js";
 import { getRoot } from "./utils.js";
+import { type Locale } from "../libs/types/core.js";
 
 type Pair = [string, string];
 type Pairs = Pair[];
@@ -67,7 +68,7 @@ function validateFromURL(url: string, locale: string, checkPath = true) {
   if (!url.includes("/docs/")) {
     throw new Error(`From-URL must contain '/docs/' was ${url}`);
   }
-  if (!VALID_LOCALES_SET.has(url.split("/")[1])) {
+  if (!VALID_LOCALES_SET.has(url.split("/")[1] as Locale)) {
     throw new Error(`The locale prefix is not valid or wrong case was ${url}`);
   }
   checkURLInvalidSymbols(url);
@@ -121,7 +122,7 @@ function validateURLLocale(url: string) {
     throw new Error(`The URL is expected to start with /$locale/docs/: ${url}`);
   }
   const validValues = [...VALID_LOCALES.values()];
-  if (!validValues.includes(locale)) {
+  if (!validValues.includes(locale as Locale)) {
     throw new Error(`'${locale}' not in ${validValues}`);
   }
 }

libs/constants/index.d.ts

@@ -1,7 +1,9 @@
+import { type Locale } from "../types/core.ts";
+
 export const ACTIVE_LOCALES: Set<string>;
-export const VALID_LOCALES: Map<string, string>;
+export const VALID_LOCALES: Map<string, Locale>;
 export const RETIRED_LOCALES: Map<string, string>;
-export const DEFAULT_LOCALE: string;
+export const DEFAULT_LOCALE: Locale;
 export const LOCALE_ALIASES: Map<string, string>;
 export const PREFERRED_LOCALE_COOKIE_NAME: string;
 export const CSP_SCRIPT_SRC_VALUES: string[];

libs/l10n/l10n.ts

@@ -1,4 +1,4 @@
-import { Locale } from "../types/core.js";
+import { type Locale } from "../types/core.js";
 
 type LocaleStringMap = Record<Locale, string>;
 

libs/types/curriculum.ts

@@ -1,3 +1,4 @@
+import { type Locale } from "./core.js";
 import { BuildData, Doc, DocParent } from "./document.js";
 
 export enum Topic {
@@ -69,5 +70,5 @@ export interface ReadCurriculum {
 }
 
 export interface CurriculumBuildData extends BuildData {
-  metadata: { locale: string } & CurriculumMetaData;
+  metadata: { locale: Locale } & CurriculumMetaData;
 }

libs/types/document.ts

@@ -1,3 +1,4 @@
+import { type Locale } from "./core.js";
 import type { SupportStatus } from "./web-features.js";
 
 export interface Source {
@@ -128,7 +129,7 @@ export type Toc = {
 export interface DocMetadata {
   title: string;
   short_title: string;
-  locale: string;
+  locale: Locale;
   native: string;
   pageTitle: string;
   mdn_url: string;
@@ -222,7 +223,7 @@ export interface NewsItem {
 export interface BuildData {
   url: string;
   rawBody: string;
-  metadata: { locale: string };
+  metadata: { locale: Locale };
   isMarkdown: true;
   fileInfo: {
     path: string;
@@ -232,7 +233,7 @@ export interface BuildData {
 export interface UnbuiltDocument {
   metadata: DocFrontmatter & {
     frontMatterKeys: string[];
-    locale: string;
+    locale: Locale;
     popularity: number;
     modified: any;
     hash: any;

markdown/m2h/cli.ts

@@ -44,7 +44,7 @@ program
 
   .option("--locale", "Targets a specific locale", {
     default: "all",
-    validator: Array.from(VALID_LOCALES.values()).concat("all"),
+    validator: [...VALID_LOCALES.values(), "all"],
   })
   .argument("[folder]", "convert by folder")
   .action(

markdown/m2h/handlers/index.ts

@@ -1,9 +1,11 @@
 import fs from "node:fs";
 
+import { Handler, Handlers, State } from "mdast-util-to-hast";
+
 import { DEFAULT_LOCALE } from "../../../libs/constants/index.js";
+import { type Locale } from "../../../libs/types/core.js";
 import { code } from "./code.js";
 import { asDefinitionList, isDefinitionList } from "./dl.js";
-import { Handler, Handlers, State } from "mdast-util-to-hast";
 
 /* A utilitary function which parses a JSON gettext file
    to return a Map with each key and its corresponding localized string.
@@ -41,7 +43,7 @@ interface NotecardType {
   magicKeyword: string;
 }
 
-function getNotecardType(node: any, locale: string): NotecardType | null {
+function getNotecardType(node: any, locale: Locale): NotecardType | null {
   const types = ["note", "warning", "callout"];
 
   if (!node.children) {
@@ -85,7 +87,7 @@ function getNotecardType(node: any, locale: string): NotecardType | null {
   return null;
 }
 
-export function buildLocalizedHandlers(locale: string): Handlers {
+export function buildLocalizedHandlers(locale: Locale): Handlers {
   /* This is only used for the Notecard parsing where the "magit" word depends on the locale */
   return {
     code,

markdown/m2h/index.ts

@@ -8,9 +8,10 @@ import format from "rehype-format";
 
 import { buildLocalizedHandlers } from "./handlers/index.js";
 import { decodeKS, encodeKS } from "../utils/index.js";
+import { type Locale } from "../../libs/types/core.js";
 
 interface ProcessorOptions {
-  locale?: string;
+  locale?: Locale;
 }
 
 function makeProcessor(options: ProcessorOptions) {