RFC: I18n Routing

[timneutkens]

Edit: This RFC has shipped! Learn more: https://nextjs.org/blog/next-10#internationalized-routing

---

Goals

• Provide i18n libraries with the supported locales / the default locale / the current locale

• Provide different strategies as every application has different requirements

  • Subpath holding the locale: e.g. /[locale]/blog/hello-world
  • Different domains holding the region: e.g. example.com, example.nl (different TLD)

• Provide "language affinity", ensuring a certain user is redirected or shown their selected language once they access it for the first time

  • This is generally only done for the / route which then redirects to the previously selected language
  • This can be optional per-application

• Provide language detection

  • Leverage the Accept-Language header
  • Support setting a cookie that forces the language detection route to a certain locale, which is useful for cases where you have a language switcher and want to memorize the user's chosen language when they go back to the / route

• Support the hybrid server-side rendering and static generation use case

Non-goals

• Provide support for GeoIP solutions (potentially we'll add this in the future)
• Supporting non-standard locale tags (potentially we'll support mapping this in the future)
• Translating route segments that are not dynamic — It's very likely companies will want this, it introduces quite a bit of extra complexity though that can be solved later instead of in this RFC
• Subdomain holding the locale: e.g. [locale].example.com — Likely to be added later if there's interest

Background

Over the past few months we've talked with a lot of enterprises and mid-sized/small business about their usage / plans to adopt Next.js. A recurring theme especially with companies planning to adopt Next.js is their requirement for internationalizing and localizing their Next.js project.

Generally, this requirement is mostly related to routing. There's 3 different strategies that came up the most which are outlined in the goals section of this document.

This RFC focuses only on the routing goals of internationalization and localization, this would allow i18n libraries like react-intl, react-i18next, lingui, rosetta, and other to be used.

Once this RFC has landed we can evaluate implementing the other part of internationalization, which is translation and extraction of translation strings. However, this is handled by the currently used libraries quite well (see previous paragraph for options) – just requires some extra setup.

Proposal

Providing supported locales

Next.js has to be made aware of the concept of locales, this can be provided through next.config.js:

module.exports = {
	i18n: {
    // Targets:
	//  - Dutch in The Netherlands
	//  - Dutch in Belgium
    //  - Dutch
    //  - English in The United States
    //  - English
    locales: ['nl-NL', 'nl-BE', 'nl', 'en-US', 'en'], // order does not matter here
    defaultLocale: 'en' // the default locale to fall back to
  }
}

Setting a defaultLocale is required in every i18n library so it'd be useful for Next.js to provide it to the application.

locales is an array of UTS Locale Identifiers.

A UTS Locale Identifier tag generally looks like language-region-script (there's more parameters, they're omitted to keep the explanation short). The region and script are optional. An example: en-US (English as spoken in the United States) nl-NL (Dutch as spoken in the Netherlands) and nl (Dutch, no specific region).

Language Strategy

The main goal of this RFC is to solve the 3 strategies outlined:

• Subpath holding the locale: e.g. /[locale]/blog/hello-world

  • This approach should not require changing the pages directory. The locale will be handled outside of the pages directory structure. No pages/[locale] directory will be required.
  • The locale can be optional, e.g. /blog/hello-world would show the default locale.
    • This behavior potentially should be a configuration option
    • This approach makes language detection slightly more complicated as if the default locale is matched the routing has to go on to the homepage

• Different domains holding the locale: e.g. example.com, example.nl (different TLD)

  • the domain mapping will have to be provided in next.config.js

Locale Detection

Locale detection will be built-in based on the Accept-Language header. We'll find the closest matching locale for the supported locales that the browser is providing.

It will work on the / route which will do a 307 (temporary redirect) to the matched locale.

For example if Accept-Language: nl-NL,nl;q=0.9,en-US;q=0.8,en;q=0.7 (taken this from my own Browser which has 2 languages set up) we'd try to find nl-NL or nl first before checking for en-Us and then en. If the application supports none of these locales we'll redirect to the defaultLocale.

A Locale can be forced by setting the NEXT_LOCALE cookie to a locale that is supported by the application. E.g. NEXT_LOCALE=nl-NL

It can be disabled if needed by setting the localeDetection option in next.config.js to false:

module.exports = {
	i18n: {
    // Targets:
		//  - Dutch in The Netherlands
		//  - Dutch in Belgium
    //  - Dutch
    //  - English in The United States
    //  - English
    locales: ['nl-NL', 'nl-BE', 'nl', 'en-US', 'en'], // order does not matter here
    defaultLocale: 'en', // the default locale to fall back to
    localeDetection: false // Disable automatic locale detection on `/`
  }
}

apple.com has a client-side detection which then shows a message asking if you want to change to a different locale. If there's enough interest in this type of solution we can provide tools for this approach as well.

Data Fetching

Static Generation:

// pages/blog/[slug].js

// Incremental Static Generation / Fallback behavior are supported.

// getStaticPaths is ran once for every configured locale
// This allows you to return separate slugs for each locale
export async function getStaticPaths({locale, locales}) {
  const blogPosts = await getBlogPostsForLocale(locale)
	return blogPosts.map(post => {
		return {
			params: {
				slug: post.slug
			}
		}
	})
}

// The configured `locales` are available so that you can create a language switcher if needed
export async function getStaticProps({params, locale, locales}) {
	const post = await getBlogPostBySlugAndLocale(params.slug, locale)
  return { props: { post } } 
}

export function BlogPage({post}) {
  return <h1>{post.title}</h1>
}

Server-Side Rendering:

import { useRouter } from 'next/router'

export function getServerSideProps({ locale, locales }) {
  // locale = { raw: 'en-US' }
	// locale can later be expanded to include a parsed version of the raw locale through `new Intl.Locale`
  return { props: { locale, locales } }
}

export function DashboardPage(props) {
  // Also available from the router:
  const router = useRouter();

  // The router gives you the identical `locale` received in `getServerSideProps`
  assert.deepEqual(
   router.locale, 
   props.locale, // Passed in from `getServerSideProps` (optional)
  ) // => true

  // The router gives you the identical `locales` received in `getServerSideProps`
  assert.deepEqual(
   router.locales, 
   props.locales, // Passed in from `getServerSideProps` (optional)
  ) // => true

  return <main />
}

Search Engines / Crawlers

Initially Next.js won't automatically add in <link rel="alternate" with the different hreflang per locale given that the alternate links are highly dependent on the individual application. E.g. maybe you only have blogposts in a single language instead of multiple languages. With SSG it could potentially be known but with incremental static generation and SSR this becomes significantly complicated to provide automatically.

You can learn more about hreflang here: https://support.google.com/webmasters/answer/189077?hl=en

As said earlier in this document the automatic language detection will only run on the / route and automatically redirect to the correct locale. The reason behind this is to avoid cloaking urls / breaking crawling of the different languages. For example what if a crawler did not set Accept-Language and goes to /nl/blog/hello-world, we'd want it to be indexed and not redirected to /en/blog/hello-world (if en is the defaultLanguage).

Next.js will automatically set the lang attribute on the <html> tag.

[jportela]

Thanks for the great work on this RFC, it's really great to see better i18n support in Next.js itself!

I just have one question:

the automatic language detection will only run on the / route and automatically redirect to the correct locale

Does this means that automatic language detection only runs on the index page (ie: www.example.com), and not on subpages? (ie: www.example.com/login)

[jorisw]

Some good points there @kivohin , and I'll agree you can debate about how crucial localized paths are business wise. This of course depends on the app and the business.

For us, it comes down to not even SEO, but a professional look, and building trust. I'll concede that most users aren't eyeballing the address bar all the time, and some browsers indeed truncate it down to the hostname. But if we can prevent serving URLs in English to local customers as they go through our app (into which we may choose to deeplink from marketing emails), we would like to.

[caribou-code]

Having read this thread, I'm still unclear about whether the new built-in i18n features of Next.js 10 supports SSG. I'd already opened a separate discussion about it but thought it might be useful to ask here.

When I export a website with this localisation setup, I get the following error:

18n support is not compatible with next export

There's also a closed bug someone created about this, and the closing comment links to this thread saying it's not meant to be supported yet, but I don't see anything about that here!

[jorisw]

@caribou-code See #17078 (comment)

[caribou-code]

@jorisw thanks but I don't feel like that comment thread clarifies anything. People in there are questioning whether it's a bug, and it doesn't seem clear why SSG functions provide locale in the context object but fail to actually export the page. The thread also talks about not being able to language detect and redirect for SSG which is fair enough, but that doesn't explain why my export still doesn't work when I set localeDetection: false.

[Vadorequest]

@caribou-code I hope my answer at #18957 (reply in thread) will shed some light on this. :)

[pix2D]

Looks great! I find it unfortunate that translating non dynamic route segments is not part of this RFC. It is a hugely important feature (for SEO as well).

At least consider providing an example manually implementing it with rewrites (that's what we're currently doing ourselves in production), but having it be an official feature would be beneficial for everyone.

[svobik7]

1. Cool, I dont see any issue about this approach
2. I do not know maxihost. But my question was about how would you create localized links in your react app when there is no routing map?

Let say I have got some footer component where I show link to contact page. I as developer want to specify link just like <Link href=“contact”> and be sure that in en mutation it will resolves to /en/contact and in br mutation to /br/contacto

[esoubihe]

I meant to say that at our company we localize urls. Eg <Link href={i18n.t('/contact')} />

If you want to keep track of urls in your app you can use a namespace for page routes as we do.

<Link href={i18n.t('pageRoutes:/contact')} />

[svobik7]

Aha, you keep all your urls in translations. I have not tried this approach yet. But seems reasonable as kind of “routing map” is in fact saved in translations.

Have you found any disadvatage of this approach?

[jorisw]

But seems reasonable as kind of “routing map” is in fact saved in translations.

In the interest of separation of concerns, we keep the translations of routes in our translations files, but the definition of routes wherever the route logic is. In our case, getStaticPaths and/or exportPathMap. Example:

src/config/i18n/translations/en-GB.json:

{
   …
   'routes.settings': 'settings',
   'routes.settings.personal-info': 'personal-info',
   'routes.settings.privacy': 'privacy',
   …
}

src/pages/[locale]/[settings]/[section].tsx:

export const getStaticPaths = () => {
   // Very long, very complicated routine that generates 
   // full, translated paths for every locale based on above
   // slug structure, such as /en/settings/personal-info
}

Sadly, Next.js does not support rewrites as part of SSG. If it did, I could just generate all our translated URLs as rewrites and we wouldn't have all our hopes tied up this RFC. Also, support for rewrites as part of SSG would prevent us from having to muck around with pages for different locales on the filesystem in order to support localized routes.

[esoubihe]

Aha, you keep all your urls in translations. I have not tried this approach yet. But seems reasonable as kind of “routing map” is in fact saved in translations.

Have you found any disadvatage of this approach?

None yet. It works well because we use the string to be translated as the URL itself. The only drawback that we have would be fixed by this RFC, which is basically that we have to make one deployment per locale and build the alternative routes with express.

This also means that we have to link the page to its original route: <Link href="/regions" as={t("pageRoutes:/regions")}>

	const { routes } = pageRoutes[process.env.LOCALE];
	Object.entries(routes).forEach(([redirectFrom, redirectTo]) => {
		// Redirects routes to their portuguese counterparts
		// when on the BR website
		if (redirectFrom !== redirectTo) {
			server.get(encodeURI(redirectFrom), (req, res) => {
				res.redirect(301, redirectTo);
			});
		}

		server.get(redirectTo, (req, res) => {
			const parsedUrl = parse(req.url, true);
			const { query } = parsedUrl;
			app.render(req, res, redirectFrom, query);
		});
	});

[Vadorequest]

This RFC strongly looks like our own implementation at Next Right Now. (We only implemented "Subpath holding the locale" option)

SSG locale subpath handling:
https://github.com/UnlyEd/next-right-now/blob/118fd049195e507458132da644fee0602e45eeea/src/utils/nextjs/SSG.ts#L120-L122

Réusable usage within SSG page:
https://github.com/UnlyEd/next-right-now/blob/v2-mst-aptd-at-lcz-sty/src/pages/%5Blocale%5D/pageTemplateSSG.tsx#L32

There are a few differences, though:

• We use /[locale]/ subpath ourselves, because it's not included within the Next.js framework, but my understanding is that it'd just remove this unnecessary layer
• We resolve not only the locale (fr-FR, en) but also the language (fr, en), because both are necessary for most internationalized applications, and it should probably be built-in. See https://github.com/UnlyEd/next-right-now/blob/118fd049195e507458132da644fee0602e45eeea/src/utils/nextjs/SSG.ts#L122 (this file/helper is being re-used by all SSG pages)
• We had to use a few rewrites and redirects tricks to make / act as a dynamic router with "locale detection" https://github.com/UnlyEd/next-right-now/blob/v2-mst-aptd-at-lcz-sty/next.config.js#L111
• We provide the same API for browser/server (looks like the RFC too, but that part is a bit confusing)
• We built our own I18nLink, similar to what you intend to do with the native next/Link component. See https://github.com/UnlyEd/next-right-now/blob/v2-mst-aptd-at-lcz-sty/src/components/i18n/I18nLink.tsx#L32
• You didn't mention usage within _document, but I assume you'd make it available there also, we use it to dynamically generate locale-based CSS classes at the top-level body. See https://github.com/UnlyEd/next-right-now/blob/v2-mst-aptd-at-lcz-sty/src/pages/_document.tsx#L91

Overall, this RFC looks like it does everything NRN do, and even more in a near future. I'd say it looks really great and I (personally) love it that you intend to implement it so similarly compared to NRN. Kinda means we were on the right track of things 😄

[AndrewIngram]

Some use cases we had at my last job, not particularly unique but worth highlighting:

• Not every page was available to each country. When we introduced a new country, a few pages nearly always existed such as the homepage, the rest were rolled out slowly or never.
• Some pages were merely translations, some were completely bespoke to each country. Our "about" page was simply translated for each country using the Lingui library, so there was only one "version" of the page. On the other end of the spectrum, our homepage was completely bespoke for each country -- i.e. a different page entry point.
• Language and country were truly independent. We were selling products to specific markets that were legally only available to those markets -- we couldn't sell our UK products to people in Spain for example. Browser accept headers couldn't be used, we had to use GeoIP (touched upon above). If a Spanish person based in England accessed the website, they'd be directed to the GB version of the site, which in an ideal world would have been translated to Spanish (sadly it wasn't).

These use cases (along with the translated static segments mentioned in the original post) were the primary motivators for me creating our own route config library (https://github.com/Zegocover/next-route-resolver). I can't see me moving away from such a library entirely (because I much prefer a config file to the pages directory for managing routes), but it'll be exciting to see more of its use cases support natively.

[Vadorequest]

Very interesting use-cases.

I might add that GeoIP is very complicated, but also becoming quite a requirement for GDPR, because lots of legal stuff depends upon the actual localization of the user, not just the locale/language they like their browser to show content.

Also, GeoIP is not free (AFAIK), and I wonder how would such a feature fit within Next.js/Vercel.

[danlaush]

Yeah, this is pretty important to us too. Locale somewhat-ambiguously refers to both language and location, which we need to manage separately. Different products are available in different locations, but the user should be able to see that location's content in any language.

[smakosh]

Finally, been looking forward to the last one! "Setting lang to the html tag"

[Vadorequest]

Will this RFC eventually cover optimization of fetching translations?

I'm asking because optimization is strongly related to the way the data is used, and is very different whether handled server or client side.

For instance, in Next Right Now, we implemented two presets/examples using GraphCMS (Headless CMS) and Airtable.

Eventually, we had to build a built-in caching mechanism to make sure not to overfetch during initial build (SSG) or on the server side (SSR) to avoid hitting the 3rd party API too often (Locize), which would incur much higher costs. It wasn't a simple task to make sure all the proper caching mechanisms were in place.

Usage:
https://github.com/UnlyEd/next-right-now/blob/118fd049195e507458132da644fee0602e45eeea/src/utils/nextjs/SSG.ts#L124

Implementation (with LOTS of documentation):
https://github.com/UnlyEd/next-right-now/blob/118fd049195e507458132da644fee0602e45eeea/src/utils/i18n/i18nextLocize.ts#L342-L382

Docs extract:

/**
 * Fetch translations from Locize API (both base translations + translations that are specific to the customer)
 *
 * We use a "common" namespace that contains all our translations
 * It's easier to manage, as we don't need to split translations under multiple files (we don't have so many translations)
 * (that may be a bit more optimized to split them under different namespaces, but that feels like anticipated optimization that isn't needed atm)
 *
 * We don't use the Locize backend for fetching data, because it doesn't play well with Next framework (no serverless support)
 * @see https://github.com/isaachinman/next-i18next/issues/274
 *
 * Instead, we manually fetch (pre-fetch) the translations ourselves from getServerSideProps/getStaticProps (or getInitialProps)
 * @see https://github.com/i18next/i18next/issues/1373
 *
 * XXX Make sure you don't use "auto" publish format, but either "nested" or "flat", to avoid the format to dynamically change (We use "nested")
 * @see https://faq.locize.com/#/general-questions/why-is-my-namespace-suddenly-a-flat-json
 *
 * XXX Caching is quite complicated, because the caching strategy depends on the runtime engine (browser vs server), the stage (development, staging, production) and the rendering mode (SSG, SSR)
 * For instance, we don't want to cache in development/staging, but we do for production in order to improve performances and decrease network usage (when using SSR)
 * When using SSG, caching doesn't matter because the pre-fetch is performed during the initial build (build time) and never at run time, so we don't need a caching mechanism
 *
 * Also, we want to invalidate the cache as soon as a new version is deployed, so that the end-users get the latest version immediately
 * (and avoid missing translations because we'd be using a cached version)
 * @see https://github.com/i18next/i18next/issues/1373
 *
 * Explanation about our cache implementation:
 *  - Browser:
 *    * In-memory: Once the translations are fetched from Locize, they're memoized
 *      - Development/staging stages:
 *        - It's very useful in development/staging, where we don't have any browser caching enabled, because it'll reduce the API calls
 *          With this in-memory cache, the Locize API will be hit only once by the browser, and then the in-memory cache will take over when performing client-side navigation
 *        - The in-memory cache will be invalidated as soon as the page is refreshed (F5, cmd+r, etc.) and a new API call will be made
 *        - XXX Without in-memory cache, a new API call would be sent for each page transition, which is slower, costly and not necessary
 *    * Browser's local cache:
 *      - Development/staging stages:
 *        - The browser's local cache is completely disabled in development/staging, so that we may work/test with the latest translation
 *          See the official recommendations https://docs.locize.com/more/caching
 *      - Production stage:
 *        - When in production, the browser will also cache for 1h, because we configured a "Cache-control: Max-Age" at https://www.locize.app/p/w7jrmdie/settings
 *          We followed the official recommendations https://docs.locize.com/more/caching
 *          1h seems to be a good compromise between over-fetching (we don't expect our users to use the app for more than 1h straight)
 *          and applying translation "hot-fix" (worst case: "hot-fix"" be applied 1h later, which is acceptable)
 *          XXX SSG pages won't be affected by changes made in Locize once the app is built. A rebuild will be necessary to update the translations
 *        - The browser's local cache will be invalidated as soon as a new release of the app is deployed,
 *          because the value of "build" in the "loadPath" url will change and thus the browser will not use its cached version anymore
 *  - Server (XXX this affects SSR pages in particular, as mentioned above):
 *    * In-memory: Once the translations are fetched from Locize, they're memoized
 *      - Development:
 *        - Once the translations are memoized, they'll be kept in-memory until the server restarts
 *          Note that full page reload may clear the cache if max-age is reached
 *      - Staging/production:
 *        - Once the translations are memoized, they'll be kept in-memory until... God knows what.
 *          - It's very hard to know how/when the memoized cache will be invalidated, as it's very much related to AWS Lambda lifecycle, which can be quite surprising
 *          - It will likely be invalidated within 5-15mn if there aren't any request performed against the Lambda (when nobody is using the app)
 *          - But if there is a steady usage of the app then it could be memoized for hours/days
 *          - If there is a burst usage, then new lambdas will be triggered, with their own version of the memoized cache
 *            (thus, depending on which Lambda serves the requests, the result could be different if they don't use the same memoized cache)
 *            This could be the most surprising, as you don't know which Lambda will serve you, so you may see a different content by refreshing the page
 *            (especially when browser cache is disabled, like when using the browser in Anonymous mode)
 *        - To sum up: The memoized cache will be invalidated when the server restarts
 *          - When a new release is deployed (this ensures that a new deployment invalidates the cache for all running Lambda instances at once)
 *          - When a Lambda that serves the app is started
 *        - The in-memory cache is automatically invalidated after 1h (see memoizedCacheMaxAge). Thus ensuring that all Lambdas will be in-sync every hour or so,
 *          even when hot-fixes are deployed on Locize
 *    * Server's local cache:
 *      - Development:
 *        - There is no known server-side caching abilities while in development, and we already rely on our in-memory cache while in development
 *      - Staging/production:
 *        - We could use on-disk caching mechanism during build, but it's not necessary because our in-memory cache is less complicated and doesn't require a writable file system
 *
 * @param {string} lang
 * @return {Promise<string>}
 */

As you can see, it got complicated real fast. Between client/server and development/staging/production, the rules for caching are quite different in order to provide the best DX and UX.

Is that something you're thinking of helping about at some point in the future? I'm conscious it's out of the scope of the first version of this RFC, but might it be built-in within Next.js, eventually?

[omarryhan]

Awesome! Glad to finally see Next.js starting to add i18n features.

I have a couple of questions:

1. Why not make next/link accept an optional locale or language attribute?
2. You mention that there will be language detection and automatic rerouting done on the "/" path. I assume since it involves cookie setting and HTTP header reading that it will require a serverside function to work. Does that mean that you can't use i18n with next export i.e. fully static Next.js websites?
3. Will the 404 page be translateable?
4. Will the _app.js component be translateable?
5. Will _document.js be able to pickup the locale in order to set it in the html lang attribute or will that be handled automatically?
6. Last, uber.com has a unique i18n strategy in which each the country and the language have their separate URL segment. E.g. https://uber.com/eg/ar (Egypt/Arabic). Will that be possible to achieve with this RFC? Or is it an overkill and ar-EG alone would suffice for most use cases?

[Vadorequest]

1. Why not make next/link accept an optional locale or language attribute?

I second that. It's very handy for i18n "switch locale" links. We implemented it that way in NRN. https://github.com/UnlyEd/next-right-now/blob/118fd04919/src/components/i18n/I18nLink.tsx#L36-L37

3. Will the 404 page be translateable?

Discussed in #12477 and not possible right now, but it should be.

4. Will the _app.js component be translateable?

It should be, since locale/locales are provided to the SSG/SSR page, it can be forwarded to _app. (that's how NRN works already)

[omariosouto]

This support will be really amazing, today in the current solution that I'm working on we use exportPathMap to have i18n support by subfolder.

[Vadorequest]

@omariosouto Did you have a look at NRN? We implemented a similar design.

Demo: https://nrn-v2-mst-aptd-at-lcz-sty-c1.vercel.app
Doc: https://unlyed.github.io/next-right-now/available-presets/v2-mst-aptd-gcms-lcz-sty

It might not be worth the trouble to change your current app to support it this way, but from what I've seen it will eventually work very closely to what Next Right Now does right now.

[raibima]

Thanks, been waiting for this feature for a long time 🙌🏾 Question: will it let us do client-side navigation when changing the locale, or full page reload is still needed?

[Vadorequest]

When doing language change in https://nrn-v2-mst-aptd-at-lcz-sty-c1.vercel.app/ (Footer, bottom right) it does it client-side. I'm confident the same behaviour will be possible with the upcoming native implementation 😃

[janus-reith]

I'm curious how locale detection would be solved in the underlying serverless environment, I'd expect the function for that to have some startup time, resulting in longer response times than serving the static content from a CDN. Wonder if there is any more sophisticated approach to this than Lambda@Edge.

[firatoezcan]

Static pages on CDNs are already hosted by webservers and most of them can still do the redirect. If you host it yourself you can also do it with the nginx-extras package, same thing for the CDNs. No function, no magic serverless, just plain ol' web.

[Vadorequest]

That's what I believe can be done, I'm just not familiar enough with CDNs to go into those waters.

But I believe a solution within Vercel (built-in) will likely be available if ever needed.

[janus-reith]

@firatoezcan Sure I could do locale detection with nginx, have no serverless function invocation and serve static files from some webserver, but that's not what I'm looking for. Also I don't want to take care of scaling nginx.

I would currently have some serverless function(Lamba) which emits the SSG Pages, and some CDN in front of that(Cloudfront).
Incoming requests would be answered right by the CDN with static html if possible, else fall back to the function invocation to create it, but I don't see that being the case with locale detection. And I believe Vercel is using a serverless appraoch which may or not may follow a similar structure, but has to deal with the same basic constraints and concepts in the end.

As outlined initially, I'm curious how this would be solved best with a serverless approach and how vercel does it, and how nextjs would provide a solution that works agnostic of the environment.

[nfantone]

I had a similar discussion with the creator of next-i18next a few weeks back. I feel like modern meta-frameworks, such as Next.js, are growing radially in all directions, trying to cater to too much.

I can't help but agree with the nginx/CF/Apache suggestions. That's software that already provides efficient solutions to the whole i18n conundrum, while still being relatively easy to pull off. Why, then, try to cram every use case at the library level? Some things are better left off to upper layers, where the domain of the solution is just better suited to tackle the problem. Don't get me wrong: it's great that Next.js provides support for i18n. This is a notoriously hard feature to implement right and there is a need for that (users still need to plug in translated text and localised content, somehow!). I say we focus on what JS frameworks can do in that regard, let web servers handle the rest and ease off a bit in this pursuit of "just add water" solutions to every possible scenario.

[janus-reith]

@timneutkens Regarding my initial question, I would appreciate if you could share some details about your take on this.

[aralroca]

I am very happy to see this RFC. Something like this is needed. 😊

Subpath holding the locale: e.g. /[locale]/blog/hello-world
Subdomain holding the locale: e.g. [locale].example.com
Different domains holding the region: e.g. example.com, example.nl (different TLD)

With these strategies in place, how will they be managed at the navigation level?

For example, the first one, how would it be like from next/link or next/router to navigate? If we enter /nl/about, the <Link href="/contact" /> will go to /nl/contact? (being "nl" the current language of the web). And to force the language change? One proposal would be to put the 'locale' (optional). Ex:

<Link locale="es" href="/contact" />

Would this also fit into this proposal? Or how will this be handled?

[Vadorequest]

Good point. All the current examples in the RFC are compatible with the "Subpath holding the locale" mode, but they don't seem compatible with "Subdomain holding the locale" mode, etc.

[aralroca]

We see SSG and SSR support, but this RFC would also work for static websites (npm run export)?

I think it's great that the language is not inside pages like pages/en/my-page.js, but should they be able to export the same page with all the languages? Or will there be this limitation and it won't work for totally static pages?

[timneutkens]

Parts of the RFC will not work with next export (e.g. language detection) given that it requires some request processing. The vast majority of Next.js applications does not use next export though.

[Vadorequest]

Language detection can be done on the browser side too. I believe a similar behavior might be possible, not sure if that'd be a good thing to do redirection from the browser though.

[martpie]

In case of npm run export, I'd recommend the web-server to redirect to the correct language. It's not too tricky to do in apache2 or nginx.

[pablopunk]

I created this solution a while ago: nextjs-redirect-locale and it does support next export using the language from the browser window.navigator.language

[Manikanta-20]

@timneutkens

this will support for custom server for express/hapi?

[devjmetivier]

Are there any API route implications for this?

I imagine it would be assumed that the developer can handle "localized" api requests by accessing headers from the request directly in the API route. I can't think of any particular use case for it, but it's fun to ask ¯_(ツ)_/¯

[dennisroethig]

Great seeing this addressed ❤️

Subdomain holding the locale: e.g. [locale].example.com

This approach can be optional for the implementation given we haven't seen as much usage of this approach. It can be added later

oww - would really love to see that happen as part of this. It's one of the things we have extremely hacky workarounds in place for and I'm excited that you're even considering it.

Hoping it doesn't fall through the cracks somewhere 🤞 😅

[grefrit]

Hey. Is it possible to somehow force pass locale to next? The RFC describes a mechanism for storing locale in cookies, but so far, as I understand it, it is not implemented. How else can you do this? And it's also very annoying when, for example, from France, but you want to use the English version of the site, but you cannot do this, because when you go to / you are redirected to the French version

[ijjk]

If you set a cookie with NEXT_LOCALE=en then the en locale will be forced, Next.js does not currently set this cookie only respects it if present.

[Vadorequest]

It sounds like another valid use-case for #18419 to be implemented, which is much easier to use than manipulating cookies.

It'd solve that particular edge case, e.g: going to / and being redirected to FR content while previously being on an /en sub page, by going to /en instead.

[saurabhbhatia]

Hi there, I just upgraded to Next 10 and modifying our code to suit the changes introduced in the new version. The following localeDetection rule doesn't seem to be working with the Next 10 release candidate. Also is there a documentation on what would be the effect of turning off locale detection ?

    localeDetection: false // Disable automatic locale detection on `/`

I want to retain the locale in a cookie or local storage so that we could remember it when the user comes back to the site again.

    const router = useRouter();
    React.useEffect(() => {
        router.replace(`/${currentLocale}`, `/${getInitialLocale()}`)
    });

import { Locale, isLocale } from "./types";

export function getInitialLocale(): Locale {
    const localSetting = localStorage.getItem("locale");
    if (localSetting && isLocale(localSetting)) {
        return localSetting;
    }

    const [browserSetting] = navigator.language.split("-");
    if (isLocale(browserSetting)) {
        return browserSetting;
    }

    return defaultLocale;
}

I want to modify this getInitialLocale to use cloudflare headers. In the current state it goes into an infinite loaded state when use a router.replace in the useEffect hook.

[IskanderMustafin]

Reagarding to localeDetection: false setting - it was fixed in 10.0.1

[omgMath]

Hey saurabhbhatia!
Were you able to find a way to remember a user-selected locale?

[saurabhbhatia]

Hey @omgMath , apologies for the late response. So when we set NEXT_LOCALE , next js reads that cookie and sends the user to the right locale next time around. We also overwrote that cookie when someone switched languages.

import Cookies from "js-cookie";

Cookies.set("NEXT_LOCALE", locale);

[omgMath]

Aaaah, thanks a lot! Seems I missed that part of the docs.

[arnaudjnn]

Is it possible to get some page using lang-locale like en-FR/my-product and all other pages with only lang en/about?

I don't want to build n * locales pages for pages like /en/about which are all the same.

[amannn]

Hi everyone,

I've just published next-intl 🌐, a minimal, but complete solution for managing internationalization in Next.js apps.

It complements the internationalized routing capabilities of Next.js by managing translations and providing them to components.

Features:

• 🌟 I18n is an essential part of the user experience, therefore this library doesn't compromise on flexibility and never leaves you behind when you need to fine tune a translation. Messages use the proven ICU syntax which covers interpolation, numbers, dates, times, plurals, ordinal pluralization, label selection based on enums and rich text.
• ⚔️ Based on battle-tested building blocks from Format.JS (used by react-intl), this library is a thin wrapper around high-quality, lower-level APIs for i18n.
• 💡 A hooks-only API ensures that you can use the same API for children as well as for attributes which expect strings.
• 🚀 Integrates with both static as well as server side rendering.

Usage:

function LatestFollower({user}) {
  const t = useTranslations('LatestFollower');

  return (
    <>
      <Text>{t('latestFollower', {username: user.name})}</Text>
      <IconButton aria-label={t('followBack')} icon={<FollowIcon />} />
    </>
  );
}

// en.json
{
  "LatestFollower": {
    "latestFollower": "{username} started following you",
    "followBack": "Follow back"
  }
}

---

I'm currently using this approach in two production apps and I'm quite happy with it. Have a look and let me know what you think! 🙂

https://github.com/amannn/next-intl

[PrimozRome]

@amannn does this package allow you to set up translated routes?

/contact
/es/contacto
/de/kontakt

or this type of dynamic routing

/[locale]/[blog-slug]/[category-slug]/[post-slug] where each URL slug can be translated?

[amannn]

AFAIK rewrites are the mechanism of Next.js to handle multilingual URLs.

As for the translated slugs, I guess it's a matter of being able to look up your relevant data based on the translated slug. I don't think an i18n solution can help here.

[aralroca]

I did a short demo video about next-translate:

• Demo video: https://www.youtube.com/watch?v=QnCIjjYLCfc
• Code: https://github.com/vinissimus/next-translate/tree/1.0.0-experimental

I hope you find this useful 😊

(sorry my English)

[ignaciolarranaga]

Hi guys. Is there any recommended approach to localize the URL ?
I mean for example:

• /en/about-us
• /es/acerca-de-nosotros

It is clearly the same page just translated (both URL and text), and indeed you can not mix language and address:

• /es/about-us
• /en/acerca-de-nosotros

For sure I can redirect from one to the other and use a component to share the implementation, or consider all the routes dynamic, but just guessing if there is a more elegant way to do it (please notice it does scales with the number of languages of the site so you end up with 50 pages that are really 1 just translated).

[javiercr]

We have a similar use case (but replacing the locale prefix with TLD domains), here is some more context.

The only way we know to achieve this with Next.js 10 is creating a routing manifest, then use it to generate the rewrites, and finally creating your own logic using the manifest to do a 404 or 301 on combinations of locales and URL segments that are not valid (eg: /es/about-us).

Not very straightforward... I hope the next version of Next.js handles this because IMHO as a SEO friendly framework this should come out of the box .

[ignaciolarranaga]

Just to comment I finally did something similar using this script in the next.config.js:

const ROUTES = [
  require('./src/components/AboutUsPage/AboutUsPage.routes.js'),
  require('./src/components/PrivacyPolicyPage/PrivacyPolicyPage.routes.js'),
  require('./src/components/TermsOfServicePage/TermsOfServicePage.routes.js'),
  ...
]

module.exports = {
  i18n: {
    locales: ['en', 'es'],
    defaultLocale: 'en',
  },

  async redirects() {
    const languageTransverseRedirects = [];
    for (routes of ROUTES) {
      for (routeSource in routes) {
        for (routeTarget in routes) {
          if (routeSource !== routeTarget) {
            languageTransverseRedirects.push({
              source: `/${routeSource}${routes[routeTarget]}`,
              destination: `/${routeTarget}${routes[routeTarget]}`,
              locale: false,
              permanent: true,
            });
          }
        }
      }
    }

    /* spellchecker: disable */
    return [
      ...languageTransverseRedirects
    ];
    /* spellchecker: enable */
  },
}

where for example AboutUsPage.routes.js is as follows:

module.exports = {
  'en': '/about-us',
  /* spellchecker: disable */
  'es': '/acerca-de-nosotros',
  /* spellchecker: enable */
}

[trompx]

Hello @ignaciolarranaga,
With those rewrites, do you manage to render a link in a language switcher that renders the correct url (the one defined in the rewrite) ?

I have a setup where I have pages like:

 /pages/appartements.js
 /pages/appartements/[slug].js

and the following rewrites:

  i18n: {
    locales: ["en", "fr"],
    defaultLocale: "fr",
    localeDetection: false,
  },
      async rewrites() {
        return [
          {
            source: "/en/appartments",
            destination: "/appartements",
            locale: false,
          },
          {
            source: "/en/appartments/:slug",
            destination: "/appartements/:slug",
            locale: false,
          },
        ];
      },

In my LanguageSwitcher.js, the next js Link component doesn't respect rewrites.

  <Link
    href={{
      pathname,
      query: query.slug ? { slug: query.slug } : null,
    }}
    locale="en"
  >
    <a>
      {locale === "fr" ? "Anglais" : "English"}
    </a>
  </Link>

When on the /en/appartements/xxxx page, the url rendered is /en/appartements/xxxx instead of /en/appartments/xxxx (without the e).
I can manually define the url with as={...} but then I have the following error: Warning: Prop href did not match. Server:

Any idea @timneutkens ? Or maybe this case is still not supported (but it the documentation is lacking on this subject so I am not sure).

[xairoo]

Just wanna share my two starters for static pages (SSG next export) - because i18n doesn't work with the current Next.js build in solution.

• https://github.com/Xairoo/nextjs-i18n-static-page-starter (i18next)
• https://github.com/Xairoo/nextjs-i18n-formatjs-static-page-starter

[kylekirkby]

Thanks @xairoo ! I also created a starter based off of a fork of yours for anyone interested.

https://github.com/linaro-marketing/serverless-nextjs-i18n-ssg-ssr-starter

[xairoo]

@kylekirkby check your(or my) build in the real world. For example calling /en/privacypolicy will return a 404. That because the server doesn't know the path [lang]/privacypolicy. So you have to use rewrite with nginx/apache/...

The next think: When loading the site the browser will request en.json or de.json multiple times (same source, same content) because of getStaticProps.

I guess I'll move to files/folders with the language slug, set the language in this file and call a component that holds the content.

[kylekirkby]

Hi @xairoo,

My example works well, specifically, with the serverless-nextjs component. I check the cookies/sub path for the lang code and return the page based on those.

[xairoo]

Hey @kylekirkby I don't use AWS. The problem with the rewrite was that I forgot to add getStaticProps & getStaticPaths to the other pages ;-)

And the thing with the requests of (lang).json is related to next/link. I use to go to an anchor and set a var to highlight the element. Setting <Link prefetch={false} ... > did the trick!

I removed react-i18next because i18next works also and it reduces the file size (~1kb).

[aralroca]

For those interested in consume translations in Next 10 with:

• 🚀 ・ Automatic page optimization.
• 🦄 ・ Easy to use and configure.
• 🌍 ・ Basic i18n support: interpolation, plurals, useTranslation hook, Trans component...
• 🈂️ ・ loading only the necessary translations (for page and for locale).
• 📦 ・ Tiny (~1kb) and tree shakable. No dependencies.

In version 1.0 of Next-translate we have made a webpack loader that automatically loads the translations without having to worry about typing in each page getStaticProps, getServerSideProps etc. The loader does it for you. And all the routing part is using the i18n routing of Next.js.

Next-translate 1.0 is just released today:

• About Next-translate 1.0
• 1.0 Release notes
• How to start with Next-translate 1.0
• Migration guide 0.x to 1.0
• Demo video with 1.0
• Examples with 1.0

[mimoid-prog]

Where can I see current goals for next realeses of this feature? Is there something like a todo list?

[ghost]

Perhaps I'm missing something, my default language is set to 'en' and my supported languages are ['en', 'es'].

When a user with language set to 'es' visits the root domain: example.com, the 'es' path is appended automatically to the url: example.com/es

However, when the same user accesses one of the pages directly, manually typing the url to a page the 'es' path isn't automatically appended.

For example, accessing: example.com/blog doesn't result in the url being rewritten to example.com/es/blog.

Is it possible to rewrite the url on all pages, urls, so users accessing a page directly via the url receive the correct translations?

[Vadorequest]

@moodledan See https://nextjs.org/docs/advanced-features/i18n-routing#sub-path-routing, it's the expected behavior and cannot be changed.

That's also the main reason why I haven't migrated to the official i18n routing implement for Next Right Now, because it's a breaking change for us.

But, it's in progress! See #18419
PR is at #19035, I have no idea when it might be shipped.

[ghost]

What are you using in the meantime @Vadorequest?

[Vadorequest]

@moodledan See #17078 (comment) 😉

[sebastian-nowak]

Is there an ETA for localizing URLs? It's crucial for SEO.

For example, an /en/about-us page should be available under /pl/o-nas, not under /pl/about-us.

[SalahAdDin]

How do you get the slugs and locales then?

[frankshwb]

E.g.: using a collection type Page, each Page has a unique slug (UID), an id, other fields and now, with the new i18n plugin, it has an localizations[] array. Here is an example

[{"id":8,"slug":"imprint","shortName":"Imprint","status":"published","locale":"en", (......)
"localizations":[{"id":10,"locale":"de-DE"}]}]

This way I can find the translated content of a Page (by id), which is a Page itself - so it also has a unique, localized slug and therefore URL.
This makes it difficult to implement a language switch with next/internationalization

[mattickx]

This line of comments is getting off-topic, let's focus on the fact that this would be a great addition if translated route-names/slugs are implemented directly into Next.JS.
As not everyone uses Strapi and this is a Next.JS discussion.

Idealy I would like to have something similar to NuxtJS (vue) where you can define the path names/slugs/dynamic params into the Page component itself. Example: https://i18n.nuxtjs.org/routing#in-component-options

This practically covers every use case, including using a headless CMS.
Thoughts?

[mimoid-prog]

Agree, I don't care about Strapi, I don't use it. I care about Next.js.
This comment also suggest the Nuxt solution #18485 (comment)

[PrimozRome]

+1 for the native Next.js solution for localised URLs. We are trying to switch our existing page to Next.js, and lack of simple solution for localised URLs is currently stopping us.

[Toolo]

I'm going to repost a question asked a few times above, as we use a similar url pattern and not being able to customize the locale format is preventing us from adopting the new i18n features:

#17078 (comment)

Last, uber.com has a unique i18n strategy in which each the country and the language have their separate URL segment. E.g. https://uber.com/eg/ar (Egypt/Arabic). Will that be possible to achieve with this RFC? Or is it an overkill and ar-EG alone would suffice for most use cases?

#17078 (comment)

Localization at Uber normally consisted of unique content per locale with additional versions of the content being translated into supported languages. I believe this (and SEO requirements) are what drove the routing nomenclature to be uber.com/{country}/{language}/ as opposed to uber.com/{language-country}/. We would publish a base page of content to the global namespace, then publish alternative (unique) versions for each country that was supported, then start the localization process. Some countries would be omitted from publishing.

#17078 (comment)

In the RFC apple.com is given as an example, and Apple implements the above strategy, and they also add the language code where necessary as a sub path e.g. https://www.apple.com/ca/fr/ for the Canadian French version of the site, which is similar to what @jasonbarone mentioned too.

Thanks for all the great new features in Next v10 by the way 🍻

[jferrettiboke]

For those who are looking for an internationalized dynamic routing example (localized dynamic page URLs), have a look at this PR that I have created to add to Next.js examples.

[SalahAdDin]

Could you add a tutorial or explanation about the stuff you did there? I don't get, for instance, why do you use [[]] at pages.

[jferrettiboke]

The README explains briefly the main concepts and link to the right documentation sections.

Check this out to learn more about the optional catch all routes feature. https://nextjs.org/docs/routing/dynamic-routes#optional-catch-all-routes

[chrillep]

It would be nice with separate link component since you would have to map urls everytime?

[jferrettiboke]

@chrillep Yeah. I did it in that way just to speed that part up. But you can have a Header module which is in charge of that.

[kimgiutae]

@jferrettiboke Thanks for the PR on this.

Me and my team are rlly looking for a way to translate URL slugs (page names) integrated with the next.js I18n power.

The only way I found practical is using the new feature of next12 of middlewares. And create a 404 errors on "incorrect" URLS with pages slugs with the wrong language, like "site.com/es/about-us". And create a correct page in the correct language "pages/nosotros.tsx". That also make us redirect the "site.com/nosotros" to 404. Is a madness I know...

Have you found some better approach to make this possible in the current version?

Thanks

[zomars]

Is there a way to override locale returned from useRouter?

Let me elaborate: Let's say we already have a preferred locale from a user in a DB. We fetch that data and want to override/overwrite the returned locale from content.locale in the server and router.locale in the client WITHOUT redirecting or changing the URL.

Any clues?

[diakonos]

I'm not sure I'm fully understanding your question.

Let's say the user has loaded your site with the locale fr, but their preferred locale is en. Which of these do you mean?

a) Display the site in English without changing the locale in the URL.
b) Simply read the en value throughout your app.

If it's b, you probably want to read/write the preferred locale in some global state after downloading it (ex. React Context, Redux, etc.). If it's a, I suppose it would depend on your i18n solution, but you should be able to simply set the i18n locale as you wish from the user preference rather than from the URL.

[zomars]

a) Display the site in English without changing the locale in the URL.

This, basically. I've already have a global state in place, but I was wondering if I can take advantage of useRouter locale prop. Since in your example it always returns the default locale (in this case fr)