feat(compiler): custom resolvers

demo/new-compiler-next16/app/.lingo/locale-resolver-client.ts

@@ -0,0 +1,96 @@
+/**
+ * Custom path-based locale resolver for Next.js client-side
+ *
+ * These are utility functions (not hooks) that can be called from anywhere,
+ * including inside callbacks, event handlers, etc.
+ *
+ * Note: We use window.location instead of Next.js hooks because these functions
+ * are called from within useCallback/event handlers where hooks cannot be used.
+ */
+
+"use client";
+
+import type { LocaleCode } from "@lingo.dev/compiler"
+import { sourceLocale } from "../../supported-locales";
+
+/**
+ * Get locale from the current pathname
+ *
+ * This is a regular function (not a hook) that can be called from anywhere.
+ * It reads from window.location.pathname to extract the locale.
+ *
+ * @returns Locale code extracted from path or default locale
+ */
+export function getClientLocale(): LocaleCode {
+  if (typeof window === "undefined") {
+    return sourceLocale;
+  }
+
+  try {
+    const pathname = window.location.pathname;
+    const segments = pathname.split("/").filter(Boolean);
+    const potentialLocale = segments[0];
+
+    if (potentialLocale) {
+      return potentialLocale as LocaleCode;
+    }
+
+    return sourceLocale;
+  } catch (error) {
+    console.error("Error resolving locale from path:", error);
+    return sourceLocale;
+  }
+}
+
+/**
+ * Get the pathname for a given locale
+ *
+ * This is a utility function that computes what the path should be for a locale change.
+ * It doesn't perform navigation - the caller is responsible for that.
+ *
+ * @param locale - Locale to switch to
+ * @returns The new pathname with the locale prefix
+ */
+function getLocalePathname(locale: LocaleCode): string {
+  if (typeof window === "undefined") {
+    return `/${locale}`;
+  }
+
+  try {
+    const pathname = window.location.pathname;
+    const segments = pathname.split("/").filter(Boolean);
+
+    // Replace the first segment (current locale) with the new locale
+    if (segments[0]) {
+      segments[0] = locale;
+    } else {
+      // If no segments, just add the locale
+      segments.unshift(locale);
+    }
+
+    return "/" + segments.join("/");
+  } catch (error) {
+    console.error("Error computing locale pathname:", error);
+    return `/${locale}`;
+  }
+}
+
+/**
+ * Returns new URL that will be used to navigate to the new locale
+ *
+ * @param locale - Locale to switch to
+ */
+export function persistLocale(locale: LocaleCode): string | undefined {
+  if (typeof window === "undefined") {
+    return;
+  }
+
+  try {
+    const newPath = getLocalePathname(locale);
+    const search = window.location.search;
+    const hash = window.location.hash;
+    return newPath + search + hash;
+  } catch (error) {
+    console.error("Error persisting locale:", error);
+  }
+}

demo/new-compiler-next16/app/.lingo/locale-resolver-server.ts

@@ -0,0 +1,29 @@
+/**
+ * Custom path-based locale resolver for Next.js server-side
+ *
+ * This resolver uses the next-intl pattern:
+ * - Middleware extracts locale from URL path
+ * - Middleware sets x-lingo-locale header
+ * - Server components read this header
+ *
+ * This allows all Server Components to reliably access the locale
+ * without needing to parse URLs or receive it via props.
+ *
+ * Falls back to the default locale if header is not set.
+ */
+
+import { headers } from "next/headers";
+
+/**
+ * Get locale from middleware-set header
+ *
+ * The middleware extracts the locale from the URL path (e.g., /es/about)
+ * and sets it in the x-lingo-locale header. This function reads that header.
+ *
+ * @returns Locale code from x-lingo-locale header or default locale
+ */
+export async function getServerLocale(): Promise<string> {
+  const headersList = await headers();
+  const locale = headersList.get("x-lingo-locale");
+  return locale || "en";
+}

demo/new-compiler-next16/app/[locale]/layout.tsx

@@ -0,0 +1,44 @@
+import type { Metadata } from "next";
+import { Geist, Geist_Mono } from "next/font/google";
+import "../globals.css";
+import { LingoProvider } from "@lingo.dev/compiler/react/next";
+import type { ReactNode } from "react";
+import type { LocaleCode } from "@lingo.dev/compiler";
+
+const geistSans = Geist({
+  variable: "--font-geist-sans",
+  subsets: ["latin"],
+});
+
+const geistMono = Geist_Mono({
+  variable: "--font-geist-mono",
+  subsets: ["latin"],
+});
+
+export const metadata: Metadata = {
+  title: "Create Next App",
+  description: "Generated by create next app",
+};
+
+export default async function LocaleLayout({
+  children,
+  params,
+}: Readonly<{
+  children: ReactNode;
+  params: Promise<{ locale: LocaleCode }>;
+}>) {
+  const { locale } = await params;
+
+  console.debug("LocaleLayout", { locale });
+  return (
+    <LingoProvider initialLocale={locale}>
+      <html lang={locale}>
+        <body
+          className={`${geistSans.variable} ${geistMono.variable} antialiased`}
+        >
+          {children}
+        </body>
+      </html>
+    </LingoProvider>
+  );
+}

demo/new-compiler-next16/app/page.tsx → demo/new-compiler-next16/app/[locale]/page.tsx

@@ -1,6 +1,6 @@
 import { Counter } from "@/components/Counter";
 import { LocaleSwitcher } from "@lingo.dev/compiler/react";
-import Link from "next/link";
+import { Link } from "@/components/LocaleLink";
 import { ServerChild } from "@/components/ServerChild";
 import { ClientChildWrapper } from "@/components/ClientChildWrapper";
 
@@ -22,7 +22,7 @@ export default function Home() {
       <header className="flex justify-between p-10 w-full">
         <span>Lingo.dev compiler Next demo</span>
         <nav>
-          <Link href="/test">Test</Link> 1
+          <Link href="test">Test</Link> 1
         </nav>
         <LocaleSwitcher
           locales={[

demo/new-compiler-next16/app/layout.tsx

@@ -1,37 +1,13 @@
-import type { Metadata } from "next";
-import { Geist, Geist_Mono } from "next/font/google";
-import "./globals.css";
-import { LingoProvider } from "@lingo.dev/compiler/react/next";
-
-const geistSans = Geist({
-  variable: "--font-geist-sans",
-  subsets: ["latin"],
-});
-
-const geistMono = Geist_Mono({
-  variable: "--font-geist-mono",
-  subsets: ["latin"],
-});
-
-export const metadata: Metadata = {
-  title: "Create Next App",
-  description: "Generated by create next app",
-};
+import { ReactNode } from "react";
 
+/**
+ * Root layout - minimal wrapper
+ * The actual locale-aware layout is in [locale]/layout.tsx
+ */
 export default function RootLayout({
   children,
 }: Readonly<{
-  children: React.ReactNode;
+  children: ReactNode;
 }>) {
-  return (
-    <LingoProvider>
-      <html>
-        <body
-          className={`${geistSans.variable} ${geistMono.variable} antialiased`}
-        >
-          {children}
-        </body>
-      </html>
-    </LingoProvider>
-  );
+  return children;
 }

demo/new-compiler-next16/components/LocaleLink.tsx

@@ -0,0 +1,19 @@
+"use client";
+
+import NextLink from "next/link";
+import { useLingoContext } from "@lingo.dev/compiler/react";
+import type { ComponentProps } from "react";
+
+/**
+ * Link component that automatically prefixes hrefs with current locale
+ */
+export function Link({ href, ...props }: ComponentProps<typeof NextLink>) {
+  const { locale } = useLingoContext();
+
+  // If href is already locale-prefixed or external, use as-is
+  const localizedHref = typeof href === "string" && !href.startsWith("http") && !href.startsWith(`/${locale}`)
+    ? `/${locale}${href.startsWith("/") ? "" : "/"}${href}`
+    : href;
+
+  return <NextLink href={localizedHref} {...props} />;
+}

demo/new-compiler-next16/next.config.ts

@@ -1,19 +1,25 @@
 import type { NextConfig } from "next";
 import { withLingo } from "@lingo.dev/compiler/next";
+import { sourceLocale } from "./supported-locales";
+import { targetLocales } from "@/supported-locales";
 
 const nextConfig: NextConfig = {};
 
 export default async function (): Promise<NextConfig> {
   return await withLingo(nextConfig, {
     sourceRoot: "./app",
     lingoDir: ".lingo",
-    sourceLocale: "en",
-    targetLocales: ["es", "de", "ru"],
+    sourceLocale,
+    targetLocales,
     useDirective: false, // Set to true to require 'use i18n' directive
     models: "lingo.dev",
     dev: {
       usePseudotranslator: true,
     },
     buildMode: "cache-only",
+    // Use custom path-based locale resolver instead of cookies
+    localePersistence: {
+      type: "custom",
+    },
   });
 }

demo/new-compiler-next16/proxy.ts

@@ -0,0 +1,107 @@
+import { NextRequest, NextResponse } from "next/server";
+import { sourceLocale, supportedLocales } from "@/supported-locales";
+
+const SUPPORTED_LOCALES = supportedLocales;
+const DEFAULT_LOCALE = sourceLocale;
+
+
+/**
+ * Get the preferred locale from Accept-Language header
+ */
+function getLocaleFromHeader(request: NextRequest): string | null {
+  const acceptLanguage = request.headers.get("accept-language");
+  if (!acceptLanguage) return null;
+
+  // Parse Accept-Language header (e.g., "en-US,en;q=0.9,es;q=0.8")
+  const languages = acceptLanguage
+    .split(",")
+    .map((lang) => {
+      const [code, qValue] = lang.trim().split(";q=");
+      const quality = qValue ? parseFloat(qValue) : 1.0;
+      // Extract base language code (e.g., "en" from "en-US")
+      const baseCode = code.split("-")[0].toLowerCase();
+      return { code: baseCode, quality };
+    })
+    .sort((a, b) => b.quality - a.quality);
+
+  // Find first supported locale
+  for (const { code } of languages) {
+    if (SUPPORTED_LOCALES.includes(code)) {
+      return code;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Extract locale from pathname
+ * Returns the locale code if found in the path, otherwise null
+ */
+function getLocaleFromPath(pathname: string): string | null {
+  // Extract first segment
+  const segments = pathname.split("/").filter(Boolean);
+  const potentialLocale = segments[0];
+
+  if (
+    potentialLocale &&
+    SUPPORTED_LOCALES.includes(potentialLocale)
+  ) {
+    return potentialLocale;
+  }
+
+  return null;
+}
+
+/**
+ * Middleware to handle locale-based routing following Next.js 16 patterns
+ *
+ * Similar to next-intl's approach:
+ * - Detects locale from URL path first
+ * - Falls back to Accept-Language header for locale detection
+ * - Redirects to appropriate locale if missing
+ * - Sets x-lingo-locale header for Server Components (like next-intl does)
+ */
+export function proxy(request: NextRequest) {
+  const pathname = request.nextUrl.pathname;
+
+  // Try to extract locale from path
+  const localeFromPath = getLocaleFromPath(pathname);
+
+  if (localeFromPath) {
+    // Already has locale in path, continue with request
+    // BUT add x-lingo-locale header so Server Components can read it
+    // This is the key pattern from next-intl!
+    const response = NextResponse.next();
+    response.headers.set("x-lingo-locale", localeFromPath);
+    return response;
+  }
+
+  // No locale in pathname - determine which locale to use
+  const preferredLocale = getLocaleFromHeader(request) || DEFAULT_LOCALE;
+
+  // Redirect to locale-prefixed path
+  const url = request.nextUrl.clone();
+  url.pathname = `/${preferredLocale}${pathname === "/" ? "" : pathname}`;
+
+  return NextResponse.redirect(url);
+}
+
+export const config = {
+  // Match all pathnames except for:
+  // - /api (API routes)
+  // - /_next (Next.js internals)
+  // - /_vercel (Vercel internals)
+  // - /favicon.ico, /robots.txt (static files in public)
+  // - Files with extensions (e.g., .js, .css, .png, .svg, etc.)
+  matcher: [
+    /*
+     * Match all request paths except for the ones starting with:
+     * - api (API routes)
+     * - _next (Next.js internals)
+     * - _vercel (Vercel internals)
+     * - Files with extensions (static files)
+     */
+    "/((?!api|_next|_vercel|.*\\..*).*)",
+  ],
+};

demo/new-compiler-next16/supported-locales.ts

@@ -0,0 +1,4 @@
+import type { LocaleCode } from "@lingo.dev/compiler"
+export const targetLocales: LocaleCode[] = ["es", "de", "ru"];
+export const sourceLocale: LocaleCode = "en";
+export const supportedLocales: LocaleCode[] = [...targetLocales, sourceLocale];

packages/new-compiler/src/index.ts

@@ -1 +1,2 @@
 export type { PartialLingoConfig } from "./types";
+export type { LocaleCode } from "lingo.dev/spec";