Splitting locale string in the URL

[markomitranic]

I'm wondering if it is possible to split the locale string in the url. For example, a locale may be fr-CA but the url subpath may be /ca/fr this is an extremely common pattern in e-commerce websites.

Furthermore, this should also work with domains, we can have a locale fr-CA which would result in example.ca/fr path.

Judging by what I read on other GitHub issues, this sounds feasible through composing middleware. I do wonder if you may have some suggestions on how to approach this in the middleware, or even pointers regarding other discussions that may be useful.

[amannn]

Yep, that's absolutely a valid case. Currently, the middleware and navigation APIs of next-intl expect a single locale prefix and I'm collecting use cases like yours in #653. Providing your own middleware and navigation APIs in these cases might be the best option for the time being.

[markomitranic]

Thats some amazing work @amannn I can't wait for the full feature set to be there so that I can go back to using the next-intl middleware. At the moment, I've made this work perfectly fine by implementing a custom middleware. To do it, we mostly use the functions that you implemented and exported, and in some cases where they aren't exported, like normalizeTrailingSlash and similar, I just copypasted your code for now.

We have 17 languages in production on this website, and it works like a charm.

/**
 * We rewrote `next-intl` middleware by dropping a bunch of
 * their functionality - because they don't support splitting
 * a locale into `domain/lang` pairs.
 */
export default function createIntlMiddleware(intlConfig: IntlConfig) {
  return (request: NextRequest): NextResponse => {
    /**
     * The currently requested domain.
     */
    const domain = findDomainByHostname(
      intlConfig.domains ?? [],
      request.nextUrl.protocol +
        "//" +
        (request.headers.get("Host") ?? request.nextUrl.host),
    );

    /**
     * The target locale of the request.
     * Based on the path prefix and the domain locales.
     */
    const locale =
      resolveLocaleFromPrefix(
        (domain.locales as Locale[]) ?? [],
        request.nextUrl.pathname,
      ) ?? domain.defaultLocale;

    /**
     * Internal pathname as Next.JS expects to see it.
     * fx. `/en/contact` -> `/en-GB/contact`
     */
    const internalPathname = resolveInternalPathname(
      request.nextUrl.pathname,
      locale,
      intlConfig.pathnames,
      domain.defaultLocale,
    );

    const url = request.nextUrl.clone();
    url.pathname = internalPathname;

    // Redirection.io middleware doesn't like trailing slashes combined with / paths.
    // This has nothing to do with next-intl, but this was a nice place to put it for now.
    if (request.nextUrl.pathname === "/") {
      url.href = normalizeTrailingSlash(url.href);
    }

    const headers = new Headers(request.headers);
    headers.set(IntlConstants.HEADER_LOCALE_NAME, locale);

    return NextResponse.rewrite(url, { request: { headers } });
  };
}


/**
 * Matches the given path to an internal name of the path, as Next.JS would
 * see it. Maps possibly translated paths into their `appDir` names.
 *
 * Default Locale is used only when on multi-domain setups, to ensure that
 * users cannot use the default locale as a prefix. Otherwise it is ignored.
 *
 * @example
 * possiblyTranslatePath({}, "/butik/sku-123", "da-DK")
 * "/da-DK/shop/sku-123"
 *
 * possiblyTranslatePath({}, "/weirdpathnomatch", "da-DK")
 * "/da-DK/weirdpathnomatch"
 */
function resolveInternalPathname(
  pathname: string,
  locale: string,
  pathnames: NonNullable<IntlConfig["pathnames"]> = {},
  defaultLocale: string,
) {
  // Remove any language prefixes from the given path
  const pathWithoutPrefix = removePotentialPrefix(
    pathname,
    locale,
    defaultLocale,
  );

  const [internalPathname, localizedPathname] = getLocalizedPathname(
    pathnames,
    pathWithoutPrefix,
    locale,
  );

  // Matches a translated path.
  if (internalPathname && localizedPathname) {
    return formatTemplatePathname(
      pathWithoutPrefix,
      localizedPathname,
      internalPathname,
      locale,
    );
  }

  // Matches the internal nextjs path, but didn't match any of the translations.
  // This means that it should return 404 on this locale.
  if (internalPathname && !localizedPathname) return `/${locale}/404`;

  // Matches a shared path (or nothing). No need to translate.
  return `/${locale}${pathWithoutPrefix}`;
}

The only tricky part of this was getting your navigation components to work with my setup. To do this, I ended up not using them almost at all, and instead writing a small wrapper around getPathname:

/**
 * Helps resolve an actual URL, based on a path name.
 *
 * Similar to `getPathname` and based on it, but expanded
 * with ability to add prefixes and domain names to external links.
 * Understands the difference between internal and external link.
 *
 * **In Development:** The behaviour is different because we
 * don't use domains, and use locale strings instead of language
 * codes as prefixes: `/en-GB/test`.
 *
 * @see {@link getPathname}
 * @example
 * resolveUrl({ href: "/test", locale: "da-DK" }, "da-DK")
 * "/test"
 *
 * resolveUrl({ href: "/test", locale: "en-DK" }, "da-DK")
 * "/en/test"
 *
 * resolveUrl({ href: "/test", locale: "en-GB" }, "da-DK")
 * "https://wineandbarrels.co.uk/test"
 */
export default function resolveUrl(
  params: Parameters<typeof getPathname>[0],
  currentLocale: Locale,
  absolute = false,
): RouteUrlDefinition {
  const targetLocale = params.locale
    ? safeLocale(params.locale)
    : currentLocale;
  const targetDomain = findDomainByLocale(intlConfig.domains, targetLocale);
  const currentDomain = findDomainByLocale(intlConfig.domains, currentLocale);

  const isCurrentDomain = targetDomain.domain === currentDomain.domain;
  const isDefaultLocale = targetDomain.defaultLocale === targetLocale;
  const languageCode = env.NEXT_PUBLIC_FORCE_SINGLE_DOMAIN
    ? targetLocale
    : targetLocale.split("-")[0];

  let urlBase = "";
  if (!isCurrentDomain || absolute) urlBase += targetDomain.domain;
  if (!isDefaultLocale) urlBase += "/" + languageCode;
  const pathname = getPathname({ ...params, locale: targetLocale });

  return {
    href: urlBase + pathname,
    locale: targetLocale,
    type: isCurrentDomain && !absolute ? "relative" : "absolute",
    changedLocale: currentLocale !== targetLocale,
  };
}

This is then used in our own Route components (I know you called it Link but most frameworks I've seen in my life call building a url based on an internal identifier a route so I went with that, to differentiate from Next's Link and your Link.

[amannn]

Damn, just read your comment here again! 😄 Quite impressive what you put together!

Just one question: In your Route, do you read the current domain via request headers? I came to the conclusion that different locale prefixes per domain can not be realized if you want to retain the ability to render pages statically. Due to this, I'm currently thinking to close #1055 as a "won't fix" and suggest different builds per domain instead (see also #1055 (comment)).

[markomitranic]

That is a very good question, and honestly, I don't remember 🤣 I spent a lot of time looking at how you do it, so I assume i copied it from you, let me check.

In the middleware, we do the headers:

    const domain = findDomainByHostname(
      intlConfig.domains ?? [],
      request.nextUrl.protocol +
        "//" +
        (request.headers.get("Host") ?? request.nextUrl.host),
    );

However, everywhere else in the app, I base the decision purely on the current locale. I have pondered the question of "what if i have the same locale on two domains" but in my case, I was in luck - I decided that this will simply not be the case. We have an ecomm store, which means that domains and locales match markets and stores. If i were to have a second en-GB locale, it would be for a smaller brand-store, which I would treat as a separate project. Knowing how thorough you are, this strategy is probably not sufficient for use with next-intl.

/**
 * Match one of the domain definitions in the configuration.
 * Simply finds a domain where the given locale string matches.
 *
 * @example
 * findDomainByLocale([], "da-DK")
 */
export default function findDomainByLocale(
  domains: NonNullable<IntlConfig["domains"]>,
  locale: string,
) {
  const definiton = domains.find((definition) =>
    definition.locales?.some((definitionLocale) => definitionLocale === locale),
  );

  if (definiton) return definiton;
  throw Error(`Provided locale ${locale} matches no domains`);
}

I think that the only way to do real multi domain with duplicate locales would be to prop drill the domain in a similar way to what we do with locale. The domain var could initially be deduced based on a combo of headers and locale, and then stored in the cache/context just like the locale. This would allow my components to simply ask for it...

[markomitranic]

@amannn why do you think that it is not possible to statically render across multiple domains tho? Seems to work perfectly fine for me, with multiple domains (at this point I've got over 20) as well as multiple locales per domain.

And with having no prefix on default locale on each domain, while having a prefix on other locales of the same domain.

Am i missing something?

[amannn]

However, everywhere else in the app, I base the decision purely on the current locale. I have pondered the question of "what if i have the same locale on two domains" but in my case, I was in luck - I decided that this will simply not be the case

Ah yep, that simplifies it slightly I guess.

next-intl has to consider the case where multiple domains use the same locales though, e.g.:

example.com/en
example.ca/en
example.ca/fr

E.g. example.com could choose to use a as-needed strategy, but potentially on the example.ca domain you might want to make it more explicit with always.

I think that the only way to do real multi domain with duplicate locales would be to prop drill the domain in a similar way to what we do with locale.

Yep, you'd have to map from the middleware to an internal pathname structure like [domain]/[locale].

However, the other part is when rendering a <Link /> (or <Route />) in your case, you'd have to resolve the inverse way from a pathname like /about to potentially adding a locale prefix based on the domain.

So yes, I think prop-drilling the domain throughout your app could help to make this use case possible. The alternative would be the headers()/cache()-based workaround that we already use for passing the locale deeply. But honestly, I'm quite hesitant with that—at least with the current state of functionality that Next.js gives us. I think if vercel/next.js#58862 were a thing, then we could reconsider this. Still, it would require a new [domain] segment on the user side, so it unfortunately isn't as frictionless as currently, where you can switch between different routing setups without having to adjust anything within your app. Due to this, I wonder if deploying the same app separately for each domain could be the easier choice anyway … Do you see any downside with that?

Does that match your understanding? Btw. thanks a lot for sharing your thoughts here, you clearly did your homework while setting that e-commerce app up! 😄 Do you have a link to it? Would be curious!