From 08f04c865ca71ee05f948827d4be8bf2a36ef2e2 Mon Sep 17 00:00:00 2001
From: Osama Mabkhot <99215291+O2sa@users.noreply.github.com>
Date: Sat, 14 Nov 2026 02:16:37 +0300
Subject: [PATCH] perf(i18n): apply transparent rewrite, static pages, and
 zero-fouc theme

- Route directory restructured from src/app/ to src/app/[locale]/ with generateStaticParams() pre-rendering static HTML (SSG) for English and Arabic.
- Middleware transparently rewrites unprefixed URLs (/, /leaderboard, etc.) directly to localized pages with zero URL redirect flicker.
- Bypasses static assets, metadata files (manifest.webmanifest, robots, sitemap), and API routes from rewrite.
- Retains inline blocking script in head for 0ms initial theme FOUC prevention and keeps client-side language switching reactive without router.refresh() to avoid theme flashing.
- Adds darkreader-lock to suppress browser extension hydration mismatches and disables unused logo preload.
- Adds comprehensive unit test suite in src/lib/i18n/tests/middleware.test.ts.
---
 next.config.js                                |  1 -
 src/app/{ => [locale]}/layout.tsx             | 43 +++++++------
 .../leaderboard/[country]/loading.tsx         |  0
 .../leaderboard/[country]/page.tsx            |  8 +--
 .../{ => [locale]}/leaderboard/loading.tsx    |  0
 src/app/{ => [locale]}/leaderboard/page.tsx   |  0
 src/app/{ => [locale]}/page.tsx               |  0
 .../scoring-methodology/page.tsx              |  0
 .../user/[username]/loading.tsx               |  0
 .../{ => [locale]}/user/[username]/page.tsx   |  2 +-
 src/components/layout/app-header.tsx          |  2 +-
 src/components/layout/brand-logo.tsx          |  2 +-
 src/components/providers/theme-provider.tsx   | 12 ++++
 src/components/seo/json-ld.tsx                |  1 +
 .../scoring/tests/scoring-methodology.test.ts |  9 ++-
 src/lib/i18n/tests/middleware.test.ts         | 60 ++++++++++++++++++
 src/middleware.ts                             | 61 ++++++++++++-------
 17 files changed, 150 insertions(+), 51 deletions(-)
 rename src/app/{ => [locale]}/layout.tsx (79%)
 rename src/app/{ => [locale]}/leaderboard/[country]/loading.tsx (100%)
 rename src/app/{ => [locale]}/leaderboard/[country]/page.tsx (95%)
 rename src/app/{ => [locale]}/leaderboard/loading.tsx (100%)
 rename src/app/{ => [locale]}/leaderboard/page.tsx (100%)
 rename src/app/{ => [locale]}/page.tsx (100%)
 rename src/app/{ => [locale]}/scoring-methodology/page.tsx (100%)
 rename src/app/{ => [locale]}/user/[username]/loading.tsx (100%)
 rename src/app/{ => [locale]}/user/[username]/page.tsx (99%)
 create mode 100644 src/lib/i18n/tests/middleware.test.ts

diff --git a/next.config.js b/next.config.js
index 073b486..bafd044 100644
--- a/next.config.js
+++ b/next.config.js
@@ -2,7 +2,6 @@
 const nextConfig = {
   output: "standalone",
   reactStrictMode: true,
-  typedRoutes: true,
   images: {
     unoptimized: true,
     remotePatterns: [
diff --git a/src/app/layout.tsx b/src/app/[locale]/layout.tsx
similarity index 79%
rename from src/app/layout.tsx
rename to src/app/[locale]/layout.tsx
index ba575c8..963e249 100644
--- a/src/app/layout.tsx
+++ b/src/app/[locale]/layout.tsx
@@ -1,19 +1,11 @@
-import "./globals.css";
+import "@/app/globals.css";
 import type { ReactNode } from "react";
 import type { Metadata } from "next";
-import { cookies, headers } from "next/headers";
-import {
-  DEFAULT_LOCALE,
-  LOCALE_COOKIE,
-  getLocaleDir,
-  isSupportedLocale,
-  parseAcceptLanguage,
-  supportedLocales,
-} from "@/lib/i18n/core";
+import { DEFAULT_LOCALE, getLocaleDir, isSupportedLocale, supportedLocales } from "@/lib/i18n/core";
 import { getMetadataBase, toAbsoluteUrl } from "@/lib/seo";
 import { AppHeader } from "@/components/layout/app-header";
 import { AppFooter } from "@/components/layout/app-footer";
-import Providers from "./providers";
+import Providers from "@/app/providers";
 
 const themeInitScript = `
   try {
@@ -96,21 +88,34 @@ export const metadata: Metadata = {
     shortcut: "/logo.svg",
     apple: "/logo.svg",
   },
+  other: {
+    "darkreader-lock": "",
+  },
 };
 
-export default async function RootLayout({ children }: { children: ReactNode }) {
-  const cookieStore = await cookies();
-  const headerStore = await headers();
-  const cookieLocale = cookieStore.get(LOCALE_COOKIE)?.value || headerStore.get("x-locale");
-  const initialLocale = isSupportedLocale(cookieLocale)
-    ? cookieLocale
-    : parseAcceptLanguage(headerStore.get("accept-language"), supportedLocales, DEFAULT_LOCALE);
+export function generateStaticParams() {
+  return supportedLocales.map((locale) => ({ locale }));
+}
+
+export default async function RootLayout({
+  children,
+  params,
+}: {
+  children: ReactNode;
+  params: Promise<{ locale: string }>;
+}) {
+  const { locale } = await params;
+  const initialLocale = isSupportedLocale(locale) ? locale : DEFAULT_LOCALE;
   const dir = getLocaleDir(initialLocale);
 
   return (
     <html lang={initialLocale} dir={dir} suppressHydrationWarning>
       <head>
-        <script id="theme-init" dangerouslySetInnerHTML={{ __html: themeInitScript }} />
+        <script
+          id="theme-init"
+          dangerouslySetInnerHTML={{ __html: themeInitScript }}
+          suppressHydrationWarning
+        />
       </head>
       <body>
         <Providers initialLocale={initialLocale}>
diff --git a/src/app/leaderboard/[country]/loading.tsx b/src/app/[locale]/leaderboard/[country]/loading.tsx
similarity index 100%
rename from src/app/leaderboard/[country]/loading.tsx
rename to src/app/[locale]/leaderboard/[country]/loading.tsx
diff --git a/src/app/leaderboard/[country]/page.tsx b/src/app/[locale]/leaderboard/[country]/page.tsx
similarity index 95%
rename from src/app/leaderboard/[country]/page.tsx
rename to src/app/[locale]/leaderboard/[country]/page.tsx
index baf8128..f67c4f3 100644
--- a/src/app/leaderboard/[country]/page.tsx
+++ b/src/app/[locale]/leaderboard/[country]/page.tsx
@@ -12,7 +12,7 @@ type CountryInfo = {
 };
 
 type Props = {
-  params: Promise<{ country: string }>;
+  params: Promise<{ locale?: string; country: string }>;
 };
 
 const countries = countriesData as CountryInfo[];
@@ -98,9 +98,9 @@ export const revalidate = 3600; // Cache on Vercel Edge CDN for 1 hour via ISR
 export const dynamicParams = true;
 
 export async function generateStaticParams() {
-  // Pre-render the top 20 most visited countries at build time.
-  // Other countries are generated on-demand upon first visit and cached by ISR.
-  return countries.slice(0, 20).map((country) => ({ country: country.slug }));
+  // Countries are generated on-demand upon first visit and cached by ISR for 1 hour.
+  // Returning an empty list avoids build-time DB/Redis connection timeouts in CI/Docker environments.
+  return [];
 }
 
 export default async function CountryLeaderboardPage({ params }: Props) {
diff --git a/src/app/leaderboard/loading.tsx b/src/app/[locale]/leaderboard/loading.tsx
similarity index 100%
rename from src/app/leaderboard/loading.tsx
rename to src/app/[locale]/leaderboard/loading.tsx
diff --git a/src/app/leaderboard/page.tsx b/src/app/[locale]/leaderboard/page.tsx
similarity index 100%
rename from src/app/leaderboard/page.tsx
rename to src/app/[locale]/leaderboard/page.tsx
diff --git a/src/app/page.tsx b/src/app/[locale]/page.tsx
similarity index 100%
rename from src/app/page.tsx
rename to src/app/[locale]/page.tsx
diff --git a/src/app/scoring-methodology/page.tsx b/src/app/[locale]/scoring-methodology/page.tsx
similarity index 100%
rename from src/app/scoring-methodology/page.tsx
rename to src/app/[locale]/scoring-methodology/page.tsx
diff --git a/src/app/user/[username]/loading.tsx b/src/app/[locale]/user/[username]/loading.tsx
similarity index 100%
rename from src/app/user/[username]/loading.tsx
rename to src/app/[locale]/user/[username]/loading.tsx
diff --git a/src/app/user/[username]/page.tsx b/src/app/[locale]/user/[username]/page.tsx
similarity index 99%
rename from src/app/user/[username]/page.tsx
rename to src/app/[locale]/user/[username]/page.tsx
index 7e10a4c..a18b386 100644
--- a/src/app/user/[username]/page.tsx
+++ b/src/app/[locale]/user/[username]/page.tsx
@@ -23,7 +23,7 @@ export const revalidate = 1800; // Cache user profile on Edge CDN for 30 minutes
 export const dynamicParams = true;
 
 type Props = {
-  params: Promise<{ username: string }>;
+  params: Promise<{ locale?: string; username: string }>;
   searchParams?: Promise<{ country?: string }>;
 };
 
diff --git a/src/components/layout/app-header.tsx b/src/components/layout/app-header.tsx
index 80f9468..d0ac317 100644
--- a/src/components/layout/app-header.tsx
+++ b/src/components/layout/app-header.tsx
@@ -16,7 +16,7 @@ export function AppHeader() {
     <header className="sticky top-0 z-50 w-full border-b border-border bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/60">
       <div className="container m-auto flex h-20 max-w-7xl items-center justify-between gap-3 px-4 sm:h-24">
         <Link href="/" className="shrink-0" aria-label="DevImpact home">
-          <BrandLogo priority size="md" />
+          <BrandLogo size="md" />
         </Link>
 
         <nav className="flex min-w-0 items-center gap-1.5 sm:gap-2">
diff --git a/src/components/layout/brand-logo.tsx b/src/components/layout/brand-logo.tsx
index 229c146..84e533d 100644
--- a/src/components/layout/brand-logo.tsx
+++ b/src/components/layout/brand-logo.tsx
@@ -14,7 +14,7 @@ const sizeClasses = {
   xl: "h-24 w-24 sm:h-32 sm:w-32",
 } as const;
 
-export function BrandLogo({ size = "md", className, priority = true }: BrandLogoProps) {
+export function BrandLogo({ size = "md", className, priority = false }: BrandLogoProps) {
   return (
     <span
       className={cn(
diff --git a/src/components/providers/theme-provider.tsx b/src/components/providers/theme-provider.tsx
index cadf070..9183b61 100644
--- a/src/components/providers/theme-provider.tsx
+++ b/src/components/providers/theme-provider.tsx
@@ -3,6 +3,17 @@
 import { ThemeProvider as NextThemesProvider } from "next-themes";
 import type { ReactNode } from "react";
 
+// Suppress the React 19 / next-themes false-positive warning for inline theme scripts
+if (typeof window !== "undefined" && process.env.NODE_ENV === "development") {
+  const originalError = console.error;
+  console.error = (...args: unknown[]) => {
+    if (typeof args[0] === "string" && args[0].includes("Encountered a script tag")) {
+      return;
+    }
+    originalError.apply(console, args);
+  };
+}
+
 export function ThemeProvider({ children }: { children: ReactNode }) {
   return (
     <NextThemesProvider
@@ -11,6 +22,7 @@ export function ThemeProvider({ children }: { children: ReactNode }) {
       enableSystem
       enableColorScheme
       storageKey="devimpact-theme"
+      disableTransitionOnChange
     >
       {children}
     </NextThemesProvider>
diff --git a/src/components/seo/json-ld.tsx b/src/components/seo/json-ld.tsx
index fdef8f2..b46cb12 100644
--- a/src/components/seo/json-ld.tsx
+++ b/src/components/seo/json-ld.tsx
@@ -8,6 +8,7 @@ export function JsonLd({ data }: JsonLdProps) {
       type="application/ld+json"
       // JSON-LD must be rendered as raw JSON text
       dangerouslySetInnerHTML={{ __html: JSON.stringify(data) }}
+      suppressHydrationWarning
     />
   );
 }
diff --git a/src/features/scoring/tests/scoring-methodology.test.ts b/src/features/scoring/tests/scoring-methodology.test.ts
index 25bb264..370393f 100644
--- a/src/features/scoring/tests/scoring-methodology.test.ts
+++ b/src/features/scoring/tests/scoring-methodology.test.ts
@@ -62,7 +62,14 @@ describe("scoring methodology localization", () => {
   });
 
   test("methodology route file exists", () => {
-    const routePath = resolve(process.cwd(), "src", "app", "scoring-methodology", "page.tsx");
+    const routePath = resolve(
+      process.cwd(),
+      "src",
+      "app",
+      "[locale]",
+      "scoring-methodology",
+      "page.tsx",
+    );
     const source = readFileSync(routePath, "utf8");
     expect(source.includes("ScoringMethodologyPage")).toBe(true);
   });
diff --git a/src/lib/i18n/tests/middleware.test.ts b/src/lib/i18n/tests/middleware.test.ts
new file mode 100644
index 0000000..6661c14
--- /dev/null
+++ b/src/lib/i18n/tests/middleware.test.ts
@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import { NextRequest } from "next/server";
+import { middleware } from "@/middleware";
+import { LOCALE_COOKIE } from "@/lib/i18n/core";
+
+describe("middleware transparent locale rewrite", () => {
+  it("rewrites / to /[defaultLocale] and sets cookie when no cookie exists", () => {
+    const req = new NextRequest("http://localhost:3000/");
+    const res = middleware(req);
+
+    expect(res.headers.get("x-middleware-rewrite")).toBe("http://localhost:3000/en");
+    expect(res.cookies.get(LOCALE_COOKIE)?.value).toBe("en");
+  });
+
+  it("rewrites /leaderboard to /ar/leaderboard when app-locale cookie is ar", () => {
+    const req = new NextRequest("http://localhost:3000/leaderboard", {
+      headers: {
+        cookie: `${LOCALE_COOKIE}=ar`,
+      },
+    });
+    const res = middleware(req);
+
+    expect(res.headers.get("x-middleware-rewrite")).toBe("http://localhost:3000/ar/leaderboard");
+  });
+
+  it("rewrites / based on Accept-Language when no cookie exists", () => {
+    const req = new NextRequest("http://localhost:3000/scoring-methodology", {
+      headers: {
+        "accept-language": "ar-SA,ar;q=0.9,en;q=0.8",
+      },
+    });
+    const res = middleware(req);
+
+    expect(res.headers.get("x-middleware-rewrite")).toBe(
+      "http://localhost:3000/ar/scoring-methodology",
+    );
+    expect(res.cookies.get(LOCALE_COOKIE)?.value).toBe("ar");
+  });
+
+  it("passes through without rewrite if path already starts with supported locale", () => {
+    const req = new NextRequest("http://localhost:3000/ar/leaderboard");
+    const res = middleware(req);
+
+    expect(res.headers.get("x-middleware-rewrite")).toBeNull();
+  });
+
+  it("passes through without rewrite for manifest.webmanifest and metadata files", () => {
+    const manifestReq = new NextRequest("http://localhost:3000/manifest.webmanifest");
+    expect(middleware(manifestReq).headers.get("x-middleware-rewrite")).toBeNull();
+
+    const robotsReq = new NextRequest("http://localhost:3000/robots.txt");
+    expect(middleware(robotsReq).headers.get("x-middleware-rewrite")).toBeNull();
+
+    const sitemapReq = new NextRequest("http://localhost:3000/sitemap.xml");
+    expect(middleware(sitemapReq).headers.get("x-middleware-rewrite")).toBeNull();
+
+    const faviconReq = new NextRequest("http://localhost:3000/favicon.ico");
+    expect(middleware(faviconReq).headers.get("x-middleware-rewrite")).toBeNull();
+  });
+});
diff --git a/src/middleware.ts b/src/middleware.ts
index 1d1664b..8ac9057 100644
--- a/src/middleware.ts
+++ b/src/middleware.ts
@@ -9,38 +9,53 @@ import {
 } from "@/lib/i18n/core";
 
 export function middleware(request: NextRequest) {
-  const requestHeaders = new Headers(request.headers);
+  const { pathname } = request.nextUrl;
+
+  // Bypass APIs, metadata files, and static assets
+  if (
+    pathname.startsWith("/api") ||
+    pathname === "/manifest.webmanifest" ||
+    pathname === "/robots.txt" ||
+    pathname === "/sitemap.xml" ||
+    pathname === "/favicon.ico" ||
+    /\.[a-zA-Z0-9]+$/.test(pathname)
+  ) {
+    return NextResponse.next();
+  }
+
+  // Check if pathname already starts with a supported locale (e.g. /en or /ar)
+  const pathnameLocale = supportedLocales.find(
+    (loc) => pathname === `/${loc}` || pathname.startsWith(`/${loc}/`),
+  );
+
+  // If already localized, pass through
+  if (pathnameLocale) {
+    return NextResponse.next();
+  }
+
+  // Determine target locale from cookie, then accept-language, then default
   const cookieLocale = request.cookies.get(LOCALE_COOKIE)?.value;
+  const hasValidCookie = isSupportedLocale(cookieLocale);
+  const locale = hasValidCookie
+    ? cookieLocale
+    : parseAcceptLanguage(request.headers.get("accept-language"), supportedLocales, DEFAULT_LOCALE);
 
-  if (!isSupportedLocale(cookieLocale)) {
-    const locale = parseAcceptLanguage(
-      request.headers.get("accept-language"),
-      supportedLocales,
-      DEFAULT_LOCALE,
-    );
-    requestHeaders.set("x-locale", locale);
-
-    const response = NextResponse.next({
-      request: {
-        headers: requestHeaders,
-      },
-    });
+  // Rewrite /path to /[locale]/path transparently
+  const rewriteUrl = request.nextUrl.clone();
+  rewriteUrl.pathname = `/${locale}${pathname === "/" ? "" : pathname}`;
 
+  const response = NextResponse.rewrite(rewriteUrl);
+
+  // If cookie wasn't set or was invalid, set it now for persistence
+  if (!hasValidCookie) {
     response.cookies.set(LOCALE_COOKIE, locale, {
       path: "/",
       maxAge: 60 * 60 * 24 * 365,
       sameSite: "lax",
     });
-
-    return response;
   }
 
-  requestHeaders.set("x-locale", cookieLocale);
-  return NextResponse.next({
-    request: {
-      headers: requestHeaders,
-    },
-  });
+  return response;
 }
 
 // Run only on routes that produce HTML or read the cookie. Skip Next.js
@@ -49,6 +64,6 @@ export function middleware(request: NextRequest) {
 // to stay cacheable.
 export const config = {
   matcher: [
-    "/((?!_next/static|_next/image|api|favicon.ico|robots.txt|sitemap.xml|.*\\.(?:svg|png|jpg|jpeg|gif|webp|ico|css|js|map|woff|woff2|ttf|otf)$).*)",
+    "/((?!_next/static|_next/image|api|favicon.ico|robots.txt|sitemap.xml|manifest.webmanifest|.*\\.(?:svg|png|jpg|jpeg|gif|webp|ico|css|js|map|woff|woff2|ttf|otf|webmanifest)$).*)",
   ],
 };