@intlayer/docs 6.1.6 → 7.0.0-canary.1

package/docs/en/intlayer_with_nextjs_15.md

@@ -1,7 +1,7 @@
 ---
 createdAt: 2024-12-06
-updatedAt: 2025-09-23
-title: Translate your Next.js 15 website (i18n)
+updatedAt: 2025-10-09
+title: How to translate your Next.js 15 app – i18n guide 2025
 description: Discover how to make your Next.js 15 website multilingual. Follow the documentation to internationalize (i18n) and translate it.
 keywords:
   - Internationalization
@@ -14,11 +14,31 @@ slugs:
   - doc
   - environment
   - nextjs
+  - 15
 applicationTemplate: https://github.com/aymericzip/intlayer-next-15-template
 youtubeVideo: https://www.youtube.com/watch?v=e_PPG7PTqGU
+history:
+  - version: 6.2.0
+    date: 2025-10-09
+    changes: Added docs for `useLocale` hook with `onLocaleChange` option
+  - version: 5.6.6
+    date: 2025-10-02
+    changes: Added docs for `getLocale` function on server actions
+  - version: 5.6.2
+    date: 2025-09-23
+    changes: Added docs for watch dictionaries changes on Turbopack
+  - version: 5.6.2
+    date: 2025-09-22
+    changes: Added docs for `multipleMiddlewares` helper
+  - version: 5.6.0
+    date: 2025-07-06
+    changes: Transform `withIntlayer()` function to a promise based function
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Init history
 ---
 
-# Getting Started internationalizing (i18n) with Intlayer and Next.js 15 App Router
+# Translate your Next.js 15 website using Intlayer | Internationalization (i18n)
 
 <iframe title="The best i18n solution for Next.js? Discover Intlayer" class="m-auto aspect-[16/9] w-full overflow-hidden rounded-lg border-0" allow="autoplay; gyroscope;" loading="lazy" width="1080" height="auto" src="https://www.youtube.com/embed/e_PPG7PTqGU?autoplay=0&amp;origin=http://intlayer.org&amp;controls=0&amp;rel=1"/>
 
@@ -166,7 +186,24 @@ module.exports = withIntlayer(nextConfig);
 ```
 
 > The `withIntlayer()` Next.js plugin is used to integrate Intlayer with Next.js. It ensures the building of content declaration files and monitors them in development mode. It defines Intlayer environment variables within the [Webpack](https://webpack.js.org/) or [Turbopack](https://nextjs.org/docs/app/api-reference/turbopack) environments. Additionally, it provides aliases to optimize performance and ensures compatibility with server components.
-> The `withIntlayer()` function is a promise based function.
+
+> The `withIntlayer()` function is a promise function. It allows to prepare the intlayer dictionaries before the build starts. If you want to use it with other plugins, you can await it. Example:
+>
+> ```tsx
+> const nextConfig = await withIntlayer(nextConfig);
+> const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);
+>
+> export default nextConfigWithOtherPlugins;
+> ```
+>
+> If you want to use it synchronously, you can use the `withIntlayerSync()` function. Example:
+>
+> ```tsx
+> const nextConfig = withIntlayerSync(nextConfig);
+> const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);
+>
+> export default nextConfigWithOtherPlugins;
+> ```
 
 ### Step 4: Define Dynamic Locale Routes
 
@@ -176,7 +213,10 @@ Remove everything from `RootLayout` and replace it with the following code:
 import type { PropsWithChildren, FC } from "react";
 import "./globals.css";
 
-const RootLayout: FC<PropsWithChildren> = ({ children }) => children;
+const RootLayout: FC<PropsWithChildren> = ({ children }) => (
+  // You can still wrap the children with other providers, Like `next-themes`, `react-query`, `framer-motion`, etc.
+  <>{children}</>
+);
 
 export default RootLayout;
 ```
@@ -184,7 +224,10 @@ export default RootLayout;
 ```jsx {3} fileName="src/app/layout.mjx" codeFormat="esm"
 import "./globals.css";
 
-const RootLayout = ({ children }) => children;
+const RootLayout = ({ children }) => (
+  // You can still wrap the children with other providers, Like `next-themes`, `react-query`, `framer-motion`, etc.
+  <>{children}</>
+);
 
 export default RootLayout;
 ```
@@ -192,7 +235,10 @@ export default RootLayout;
 ```jsx {1,8} fileName="src/app/layout.csx" codeFormat="commonjs"
 require("./globals.css");
 
-const RootLayout = ({ children }) => children;
+const RootLayout = ({ children }) => (
+  // You can still wrap the children with other providers, Like `next-themes`, `react-query`, `framer-motion`, etc.
+  <>{children}</>
+);
 
 module.exports = {
   default: RootLayout,
@@ -1131,8 +1177,8 @@ import { useLocale } from "next-intlayer";
 import Link from "next/link";
 
 export const LocaleSwitcher: FC = () => {
-  const { locale, pathWithoutLocale, availableLocales } = useLocale();
-  const { setLocaleCookie } = useLocaleCookie();
+  const { locale, pathWithoutLocale, availableLocales, setLocale } =
+    useLocale();
 
   return (
     <div>
@@ -1141,10 +1187,10 @@ export const LocaleSwitcher: FC = () => {
         {availableLocales.map((localeItem) => (
           <Link
             href={getLocalizedUrl(pathWithoutLocale, localeItem)}
-            hrefLang={localeItem}
             key={localeItem}
             aria-current={locale === localeItem ? "page" : undefined}
-            onClick={() => setLocaleCookie(localeItem)}
+            onClick={() => setLocale(localeItem)}
+            replace // Will ensure that the "go back" browser button will redirect to the previous page
           >
             <span>
               {/* Locale - e.g. FR */}
@@ -1183,8 +1229,8 @@ import { useLocale } from "next-intlayer";
 import Link from "next/link";
 
 export const LocaleSwitcher = () => {
-  const { locale, pathWithoutLocale, availableLocales } = useLocale();
-  const { setLocaleCookie } = useLocaleCookie();
+  const { locale, pathWithoutLocale, availableLocales, setLocale } =
+    useLocale();
 
   return (
     <div>
@@ -1193,10 +1239,10 @@ export const LocaleSwitcher = () => {
         {availableLocales.map((localeItem) => (
           <Link
             href={getLocalizedUrl(pathWithoutLocale, localeItem)}
-            hrefLang={localeItem}
             key={localeItem}
             aria-current={locale === localeItem ? "page" : undefined}
-            onClick={() => setLocaleCookie(localeItem)}
+            onClick={() => setLocale(localeItem)}
+            replace // Will ensure that the "go back" browser button will redirect to the previous page
           >
             <span>
               {/* Locale - e.g. FR */}
@@ -1235,7 +1281,8 @@ const { useLocale } = require("next-intlayer");
 const Link = require("next/link");
 
 export const LocaleSwitcher = () => {
-  const { locale, pathWithoutLocale, availableLocales } = useLocale();
+  const { locale, pathWithoutLocale, availableLocales, setLocale } =
+    useLocale();
 
   return (
     <div>
@@ -1244,10 +1291,10 @@ export const LocaleSwitcher = () => {
         {availableLocales.map((localeItem) => (
           <Link
             href={getLocalizedUrl(pathWithoutLocale, localeItem)}
-            hrefLang={localeItem}
             key={localeItem}
             aria-current={locale === localeItem ? "page" : undefined}
-            onClick={() => setLocaleCookie(localeItem)}
+            onClick={() => setLocale(localeItem)}
+            replace // Will ensure that the "go back" browser button will redirect to the previous page
           >
             <span>
               {/* Locale - e.g. FR */}
@@ -1273,11 +1320,11 @@ export const LocaleSwitcher = () => {
 };
 ```
 
-> An alternative way is to use the `setLocale` function provided by the `useLocale` hook. This function will not allow prefetching the page and will reload the page.
+> An alternative way is to use the `setLocale` function provided by the `useLocale` hook. This function will not allow prefetching the page. See the [`useLocale` hook documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/packages/next-intlayer/useLocale.md) for more details.
 
-> In this case, without redirection using `router.push`, only your server-side code will change the locale of the content.
+> You can also set a function in the `onLocaleChange` option to trigger a custom function when the locale changes.
 
-```tsx fileName="src/components/LocaleSwitcher.tsx" codeFormat="typescript"
+```tsx fileName="src/components/LocaleSwitcher.tsx"
 "use client";
 
 import { useRouter } from "next/navigation";
@@ -1557,13 +1604,3 @@ For more details on how to use the extension, refer to the [Intlayer VS Code Ext
 ### Go Further
 
 To go further, you can implement the [visual editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_visual_editor.md) or externalize your content using the [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md).
-
-## Doc History
-
-| Version | Date       | Changes                                                         |
-| ------- | ---------- | --------------------------------------------------------------- |
-| 5.6.6   | 2025-10-02 | Added docs for `getLocale` function on server actions           |
-| 5.6.2   | 2025-09-23 | Added docs for watch dictionaries changes on Turbopack          |
-| 5.6.2   | 2025-09-22 | Added docs for `multipleMiddlewares` helper                     |
-| 5.6.0   | 2025-07-06 | Transform `withIntlayer()` function to a promise based function |
-| 5.5.10  | 2025-06-29 | Init history                                                    |