diff --git a/docs/advanced-features/i18n-routing.md b/docs/advanced-features/i18n-routing.md index 5932f80d77461..219a9956e5aa1 100644 --- a/docs/advanced-features/i18n-routing.md +++ b/docs/advanced-features/i18n-routing.md @@ -234,6 +234,30 @@ Next.js doesn't know about variants of a page so it's up to you to add the `href > Note that Internationalized Routing does not integrate with [`next export`](/docs/advanced-features/static-html-export.md) as `next export` does not leverage the Next.js routing layer. Hybrid Next.js applications that do not use `next export` are fully supported. +### Dynamic Routes and `getStaticProps` Pages + +For pages using `getStaticProps` with [Dynamic Routes](/docs/routing/dynamic-routes.md), all locale variants of the page desired to be prerendered need to be returned from [`getStaticPaths`](/docs/basic-features/data-fetching.md#getstaticpaths-static-generation). Along with the `params` object returned for `paths`, you can also return a `locale` field specifying which locale you want to render. For example: + +```js +// pages/blog/[slug].js +export const getStaticPaths = ({ locales }) => { + return { + paths: [ + // if no `locale` is provided only the defaultLocale will be generated + { params: { slug: 'post-1' }, locale: 'en-US' }, + { params: { slug: 'post-1' }, locale: 'fr' }, + ], + fallback: true, + } +} +``` + +For [Automatically Statically Optimized](/docs/advanced-features/automatic-static-optimization.md) and non-dynamic `getStaticProps` pages, **a version of the page will be generated for each locale**. This is important to consider because it can increase build times depending on how many locales are configured inside `getStaticProps`. + +For example, if you have 50 locales configured with 10 non-dynamic pages using `getStaticProps`, this means `getStaticProps` will be called 500 times. 50 versions of the 10 pages will be generated during each build. + +To decrease the build time of dynamic pages with `getStaticProps`, use a [`fallback` mode](https://nextjs.org/docs/basic-features/data-fetching#fallback-true). This allows you to return only the most popular paths and locales from `getStaticPaths` for prerendering during the build. Then, Next.js will build the remaining pages at runtime as they are requested. + ### Automatically Statically Optimized Pages For pages that are [automatically statically optimized](/docs/advanced-features/automatic-static-optimization.md), a version of the page will be generated for each locale. @@ -265,24 +289,9 @@ export async function getStaticProps({ locale }) { } ``` -### Dynamic getStaticProps Pages - -For dynamic `getStaticProps` pages, any locale variants of the page that is desired to be prerendered needs to be returned from [`getStaticPaths`](/docs/basic-features/data-fetching.md#getstaticpaths-static-generation). Along with the `params` object that can be returned for the `paths`, you can also return a `locale` field specifying which locale you want to render. For example: - -```js -// pages/blog/[slug].js -export const getStaticPaths = ({ locales }) => { - return { - paths: [ - { params: { slug: 'post-1' }, locale: 'en-US' }, - { params: { slug: 'post-1' }, locale: 'fr' }, - ], - fallback: true, - } -} -``` - ## Limits for the i18n config - `locales`: 100 total locales - `domains`: 100 total locale domain items + +> **Note:** These limits have been added initially to prevent potential [performance issues at build time](#dynamic-routes-and-getStaticProps-pages). We are continuing to evaluate if these limits are sufficient. diff --git a/packages/next/server/config.ts b/packages/next/server/config.ts index a07d610f1e607..52f10d91ebde9 100644 --- a/packages/next/server/config.ts +++ b/packages/next/server/config.ts @@ -329,8 +329,8 @@ function assignDefaults(userConfig: { [key: string]: any }) { } if (i18n.locales.length > 100) { - throw new Error( - `Received ${i18n.locales.length} i18n.locales items which exceeds the max of 100, please reduce the number of items to continue.\nSee more info here: https://nextjs.org/docs/messages/invalid-i18n-config` + Log.warn( + `Received ${i18n.locales.length} i18n.locales items which exceeds the recommended max of 100.\nSee more info here: https://nextjs.org/docs/advanced-features/i18n-routing#how-does-this-work-with-static-generation` ) }