Translations in API routes (app directory)

[clement-songis]

Is your feature request related to a problem? Please describe.

We have no way to get the locale from an API route.

Describe the solution you'd like

Export resolveLocale with receiveConfig middleware functions for use in API routes

api/route.ts:

import i18n from "@/i18nConfig";
import { resolveLocale } from "next-intl/api";
export async function GET(req: NextRequest) {
    const locale = resolveLocale(req, i18n);
    const t = await getTranslator(locale, "api");
}

next-intl/api:

import { receiveConfig } from "next-intl/middleware";
import middlewareResolveLocale from "next-intl/middleware/resolveLocale";

export function resolveLocale(req: NextRequest, config: MiddlewareConfigWithDefaults) {
  const configWithDefault = receiveConfig(config);
  const { locale } = middlewareResolveLocale(
    configWithDefault,
    req.headers,
    req.cookies,
    req.nextUrl.pathname
  );
  return locale;
}

Describe alternatives you've considered

Use getLocale function and middleware with api route

api/route.ts:

import { getLocale } from "next-intl/server";
export async function GET(req: NextRequest) {
    const locale = getLocale();
    const t = await getTranslator(locale, "api");
}

middleware.ts:

export const config = {
  matcher: ["((?!_next|.*\\..*).*)"],
};

[amannn]

resolveLocale is currently not intended to be exported. You can receive the locale in your Route Handler by accepting it either as a route param or search param to be called accordingly from the client side (e.g. /api/hello?locale=en or /en/api/hello).

If you want to resolve the locale based on the accept-language header, you can use the same code that we use in the middleware (it's really not much):

next-intl/packages/next-intl/src/middleware/resolveLocale.tsx

Lines 38 to 47 in 88eabc7

	const languages = new Negotiator({
	headers: {
	'accept-language': requestHeaders.get('accept-language') || undefined
	}
	}).languages();
	try {
	locale = match(languages, locales, defaultLocale);
	} catch (e) {
	// Invalid language
	}

I'll move this to a discussion, as this is more a usage question—I hope you understand!

[proccedure-caze]

If I try to access the getTranslation inside an Route Handler it gives me the error

Unable to find 'next-intl' locale because the middleware didn't run on this request.

This is my middleware:

import { NextRequest } from "next/server";
import { withAuth } from "next-auth/middleware";
import createIntlMiddleware from "next-intl/middleware";
import { localePrefix, locales } from "./i18n.config";

const publicPages = ["/", "/login"];

const intlMiddleware = createIntlMiddleware({
  locales,
  localePrefix,
  defaultLocale: locales[0],
});

const authMiddleware = withAuth((req) => intlMiddleware(req), {
  callbacks: {
    authorized: ({ token }) => token != null,
  },
  pages: {
    signIn: "/login",
  },
});

export default function middleware(req: NextRequest) {
  const publicPathnameRegex = RegExp(
    `^(/(${locales.join("|")}))?(${publicPages
      .flatMap((p) => (p === "/" ? ["", "/"] : p))
      .join("|")})/?$`,
    "i",
  );
  const isPublicPage = publicPathnameRegex.test(req.nextUrl.pathname);

  if (isPublicPage) {
    return intlMiddleware(req);
  } else {
    return (authMiddleware as any)(req);
  }
}

export const config = {
  matcher: [
    "/",
    "/(en-US|en|it|fr|pt-BR|zh)/:path*",
    "/((?!api|_next/static|_next/image|favicon.ico).*)",
  ],
};

My route handlers are located outside of the [locale] param, as I am passing it (or not) as a query param.

|

• [locales]
  -app routes...
  |
• api
  -route handlers...

Also if I remove 'api|' from the middleware it dose not recognize some of my routes, saying that the method is forbidden.

[amannn]

My route handlers are located outside of the [locale] param

In this case you need to provide an explicit locale as it's also shown in the docs: https://next-intl-docs.vercel.app/docs/environments/metadata-route-handlers#route-handlers

[kamranayub]

@amannn I am including next-intl in my course on adding i18n to Next.js and I just wanted to mention I was looking for an export just like this. I understand reading the header probably isn't the common case, and the matching logic is fairly simple. But now I have to keep the same packages (which could drift) explicitly in the package.json, and if the matching logic ever changes, the user has to keep them in sync.

My feedback is that it would be a better developer experience to offer an easy-to-use export for passing in the incoming NextRequest for this purpose. In the course, I call out that instead of forwarding/reading the header, it may be better to use a route segment or search param explicitly -- but this is still a valid option, so I have to say something like, "next-intl uses this same logic and the same packages but it's not exported for use so we have to keep our same getLocale helper." 😅

[amannn]

Can you explain your use case in more detail? The reason why I'd recommend an explicit locale search param is because this way, when you fetch the endpoint from the client side, you can be sure that the response matches the locale of the client. If the client has explicitly switched to another locale and invokes the endpoint, you might want to respect the changed locale and not return a response based on the accept-language header.

[kamranayub]

After thinking about it some more, I think you're right. There could be a use case where someone might want to read it from the header (like a proxy Cloudflare worker) but I doubt it's a common case. I redid my material so it focuses on the URL search params and dynamic route segment. I already show how to do manual locale matching so it's not like they won't know how to do it 👍

[sovetski]

How can we use next-intl in API routes? why we don't have any example about it on the docs?

EDIT: Ok I think it is here: https://next-intl.dev/docs/environments/actions-metadata-route-handlers#route-handlers