next-intl auto-detection w/ middleware + localePrefix: 'as-needed' always returns 'en' on first visit, am I misconfiguring?

[Adebesin-Cell]

Goal: Detect locale from Accept-Language on first visit (no cookie), using localePrefix: 'as-needed'.

// routing.ts
export const routing = defineRouting({
  locales: ['en', 'kr'],
  defaultLocale: 'en',
  localePrefix: 'as-needed'
});

// middleware.ts
export default createMiddleware({
  locales: ['en', 'kr'],
  defaultLocale: 'en',
  localePrefix: 'as-needed',
  localeDetection: true
});
export const config = { matcher: ['/', '/(?!api|_next|.*\\..*).+'] };

// i18n.ts
export default getRequestConfig(async ({ requestLocale }) => {
  let locale = await requestLocale();
  if (!locale) locale = 'en';
  return { locale, messages: (await import(`../messages/${locale}.json`)).default };
});

Observed: On first visit to / with Accept-Language: ko-KR,ko;q=0.9,en;q=0.8, requestLocale() resolves to 'en'. No NEXT_LOCALE cookie present.

Questions:

1. Is my matcher or middleware setup wrong for as-needed?
2. Should requestLocale() reflect detected ko on first visit, or must I read headers manually?
3. With as-needed, should middleware redirect to /ko for non-default locales, or keep / and set a cookie?

Screenshots

The screenshot shows my browser language set to Korean (ko-KR) so the app can auto-detect my preference, but it still falls back to English. Any help would be appreciated.

[Adebesin-Cell]

Solved! 🎉
I ended up fixing it by mapping ko → kr directly in my getRequestConfig and adding a prefix mapping in defineRouting.

// routing.ts
import { localeSchema } from "@/messages/_schema";
import { createNavigation } from "next-intl/navigation";
import { defineRouting } from "next-intl/routing";

export const routing = defineRouting({
  locales: localeSchema.options,
  defaultLocale: "en",
  localePrefix: {
    mode: "as-needed",
    prefixes: {
      ko: "/kr",
    },
  },
  localeDetection: true,
});

export const { Link, redirect, usePathname, useRouter } =
  createNavigation(routing);

// request.ts
import { getRequestConfig } from "next-intl/server";
import { routing } from "./routing";
import { localeSchema } from "@/messages/_schema";

export default getRequestConfig(async ({ requestLocale }) => {
  let locale = await requestLocale;

  if (!locale || !routing.locales.includes(locale)) {
    locale = routing.defaultLocale;
  }

  if (locale === localeSchema.Enum.ko) {
    locale = localeSchema.Enum.kr;
  }

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

[amannn]

Great that you figured it out @Adebesin-Cell!

kr is the language code for the Kanuri language, but it's the country code for the Republic of Korea. Locales come in the format [languageCode]-[regionCode]-…, so the first segment should correspond to the language code (which for Korean is ko).

The mapping in the routing configuration is fine if you want to provide routing based on country codes. However, the locale that you return from request.ts should return ko in your case, not kr. What you use to structure your messages is up to you though, but a locale like ko-KR.json could be a good idea if the country is the main differentiator for your app.

[Adebesin-Cell]

Good point @amannn, thanks for flagging! In this project, we use kr as the locale identifier for Korean, with a redirect so that ko points to kr. This was a conventional choice early on since we structured locales around country codes rather than language codes.

That’s why you see kr instead of ko in the routing/config. Functionally, it’s the same, but everything stays consistent with kr (e.g., kr.json). Switching everything over to ko now would involve a significant amount of work and could also impact SEO, so we’ve stuck with kr as the standard.

[amannn]

Sure, structuring multi-lingual websites around country codes is absolutely fine (see e.g. nike.com/kr).

My comment was more about the locale that you're returning from i18n/request.ts which is for example used when formatting dates with next-intl.

E.g.:

const date = new Date();

// '2025년 8월 18일'
date.toLocaleDateString('ko', {dateStyle: 'long'})

// 'August 18, 2025'
date.toLocaleDateString('kr', {dateStyle: 'long'})

(this example uses plain JS for illustrative purposes)

So what I'd do is adjusting your i18n/request.ts to this:

import { getRequestConfig } from "next-intl/server";
import { routing } from "./routing";
import { localeSchema } from "@/messages/_schema";

export default getRequestConfig(async ({ requestLocale }) => {
  let locale = await requestLocale;

  if (!locale || !routing.locales.includes(locale)) {
    locale = routing.defaultLocale;
  }

  return {
    locale,
    messages: (await import(`../messages/${
      locale === localeSchema.Enum.ko ? 'kr' : 'en'
    }.json`)).default,
  };
});

[Adebesin-Cell]

Nice catch @amannn ❤️, thanks! That makes the setup much cleaner.