Best Practice: Mapping dynamic runtime locales to a fixed set of UI languages

[jaqubowsky]

Hi everyone

First off, thank you for your incredible work on this library.

I'm looking for the recommended "best practice" for a specific use case involving dynamic "content markets" that map to a fixed set of "UI languages."

My Requirements

1. Fixed UI Languages: I have two core UI message files: pl.json (default) and en.json.
2. Dynamic Content Markets: My headless CMS provides a dynamic list of markets (e.g., pl, en, fr, de, es, it). This list can change at runtime.
3. Mapping Logic:
   • Users visiting /pl should get the Polish UI (from pl.json).
   • Users visiting /en, /fr, /de, it, etc., should all get the English UI (from en.json), while the app remains aware of the "market" (e.g., fr) to fetch the correct content from the CMS.
4. No Rebuilds: A new market (e.g., /it) added to the CMS must work immediately without requiring a site rebuild or redeploy.

---

My Proposed Solution

Based on the documentation for async middleware, my plan is to fetch the dynamic list of markets on every request (with caching).

Here is my intended setup:

request.ts
Here, I validate the locale against the dynamic list from the CMS and then apply the mapping logic to select the correct message file.

import { hasLocale, IntlErrorCode, type Locale } from "next-intl";
import { getRequestConfig } from "next-intl/server";
import { DEFAULT_LOCALE, getAllLocales } from "@/shared/api/get-all-locales";

export default getRequestConfig(async ({ requestLocale }) => {
  const requested = await requestLocale;
  const supportedLocales = await getAllLocales();

  let locale: Locale = DEFAULT_LOCALE;

  if (supportedLocales?.length && hasLocale(supportedLocales, requested)) {
    locale = requested as Locale;
  }

  const uiLocale = locale === DEFAULT_LOCALE ? DEFAULT_LOCALE : "en";

  return {
    locale,
    messages: (await import(`../../messages/${uiLocale}.json`)).default
});

proxy.ts
Here, I pass the dynamic list of markets to createMiddleware.

import type { NextRequest } from "next/server";
import { NextResponse } from "next/server";
import createMiddleware from "next-intl/middleware";
import { DEFAULT_LOCALE, getAllLocales } from "./shared/api/get-all-locales";

export default async function proxy(request: NextRequest) {
  try {
    const locales = await getAllLocales();
    if (!locales?.length) return new NextResponse(null, { status: 404 });

    const handleI18nRouting = createMiddleware({
      locales,
      defaultLocale: DEFAULT_LOCALE,
      localePrefix: "as-needed",
    });

    return handleI18nRouting(request);
  } catch (error) {
    console.error("Error in proxy middleware:", error);
    return new NextResponse(null, { status: 500 });
  }
}

export const config = {
  matcher: [
    /*
     * Match all request paths except for the ones starting with:
     * - api (API routes)
     * - _next/static (static files)
     * - _next/image (image optimization files)
     * - favicon.ico (favicon file)
     * - robots.txt (robots file)
     * - sitemap.xml (sitemap file)
     * - manifest.json (manifest file)
     * - public (public folder)
     * - . (all files in the public folder)
     * - . (all files in the public folder)
     */
    "/((?!_next/static|_next/image|public/|favicon.ico|robots.txt|sitemap.xml|manifest.json).*)",
  ],
};

Here my routing system if it helps with anything:

app
│
├── [locale]/
│   │
│   ├── [[...slug]]/
│   │
│   ├── @cart/
│   ├── @search/
│   │
│   ├── about/
│   ├── cart/
│   ├── search/
│   ├── terms-of-service/
│   │
│   ├── error.tsx
│   ├── layout.tsx
│   └── not-found.tsx
│
└── api/

---

My Question

Is this async middleware approach-fetching the dynamic market list on each request (with caching) the intended and most robust solution for this requirement?

I want to ensure this is the most performant and correct pattern supported by next-intl, especially considering SSG/ISR. How does this dynamic-locale-list approach affect static generation for pages?

Thank you for any clarification you can provide!

[amannn]

That's an interesting use case! But yes, that looks really solid to me what you're describing.

Basically, next-intl allows you to define all of these independently:

1. Locales your routing supports (can be dynamic)
2. Locales your UI supports (can be dynamic, but subject to available messages)
3. Locales your CMS supports (can be dynamic)

In your case, 1 and 3 are the same though.

How does this dynamic-locale-list approach affect static generation for pages?

You can return all, some or none (i.e. []) locales from generateStaticParams for static rendering. If (1) can change at runtime, you might want to be prepared to render an unexpected locale though (e.g. don't use dynamicParams = false). But you can absolutely ISR' new locales at runtime.

As for navigation APIs, you can omit the locales array.

Hope this helps!