@intlayer/docs 5.5.9 → 5.5.10

package/en/intlayer_with_nextjs_page_router.md

@@ -529,67 +529,393 @@ const ComponentExample = () => {
 > value of the function as follows:
 
 > ```jsx
->
-> ```
-
 > <img src={content.image.src.value} alt={content.image.value} />
-
-> ```
->
 > ```
 
 > To Learn more about the `useIntlayer` hook, refer to the [documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/next-intlayer/useIntlayer.md).
 
-### (Optional) Step 8: Internationalize Your Metadata
+### (Optional) Step 8: Internationalization of your metadata
 
-To internationalize metadata such as page titles and descriptions, use the `getStaticProps` function in conjunction with Intlayer's `getTranslation` function.
+In the case you want to internationalize your metadata, such as the title of your page, you can use the `getStaticProps` function provided by Next.js Page Router. Inside, you can retrieve the content from the `getIntlayer` function to translate your metadata.
 
-```tsx fileName="src/pages/[locale]/index.tsx" codeFormat="typescript"
+```typescript fileName="src/pages/[locale]/metadata.content.ts" contentDeclarationFormat="typescript"
+import { type Dictionary, t } from "intlayer";
+import { type Metadata } from "next";
+
+const metadataContent = {
+  key: "page-metadata",
+  content: {
+    title: t({
+      en: "Create Next App",
+      fr: "Créer une application Next.js",
+      es: "Crear una aplicación Next.js",
+    }),
+    description: t({
+      en: "Generated by create next app",
+      fr: "Généré par create next app",
+      es: "Generado por create next app",
+    }),
+  },
+} satisfies Dictionary<Metadata>;
+
+export default metadataContent;
+```
+
+```javascript fileName="src/pages/[locale]/metadata.content.mjs" contentDeclarationFormat="esm"
+import { t } from "intlayer";
+
+/** @type {import('intlayer').Dictionary<import('next').Metadata>} */
+const metadataContent = {
+  key: "page-metadata",
+  content: {
+    title: t({
+      en: "Create Next App",
+      fr: "Créer une application Next.js",
+      es: "Crear una aplicación Next.js",
+    }),
+    description: t({
+      en: "Generated by create next app",
+      fr: "Généré par create next app",
+      es: "Generado por create next app",
+    }),
+  },
+};
+
+export default metadataContent;
+```
+
+```javascript fileName="src/pages/[locale]/metadata.content.cjs" contentDeclarationFormat="commonjs"
+const { t } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary<import('next').Metadata>} */
+const metadataContent = {
+  key: "page-metadata",
+  content: {
+    title: t({
+      en: "Create Next App",
+      fr: "Créer une application Next.js",
+      es: "Crear una aplicación Next.js",
+    }),
+    description: t({
+      en: "Generated by create next app",
+      fr: "Généré par create next app",
+      es: "Generado por create next app",
+    }),
+  },
+};
+
+module.exports = metadataContent;
+```
+
+```json fileName="src/pages/[locale]/metadata.content.json" contentDeclarationFormat="json"
+{
+  "key": "page-metadata",
+  "content": {
+    "title": {
+      "nodeType": "translation",
+      "translation": {
+          "en": "Preact logo",
+          "fr": "Logo Preact",
+          "es": "Logo Preact",
+      },
+    },
+    "description": {
+      "nodeType": "translation",
+      "translation": {
+        "en": "Generated by create next app",
+        "fr": "Généré par create next app",
+        "es": "Generado por create next app",
+      },
+    },
+  },
+};
+```
+
+````tsx fileName="src/pages/[locale]/index.tsx" codeFormat="typescript"
 import { GetStaticPaths, GetStaticProps } from "next";
-import { type IConfigLocales, getTranslation, Locales } from "intlayer";
+import { getIntlayer, getMultilingualUrls } from "intlayer";
 import { useIntlayer } from "next-intlayer";
+import Head from "next/head";
+import type { FC } from "react";
 
 interface HomePageProps {
   locale: string;
-  metadata: Metadata;
+  metadata: {
+    title: string;
+    description: string;
+  };
+  multilingualUrls: Record<string, string>;
 }
 
-const HomePage = ({ metadata }: HomePageProps) => {
-  // Metadata can be used in the head or other components as needed
+const HomePage: FC<HomePageProps> = ({
+  metadata,
+  multilingualUrls,
+  locale,
+}) => {
+  const content = useIntlayer("page");
+
   return (
     <div>
       <Head>
         <title>{metadata.title}</title>
         <meta name="description" content={metadata.description} />
+        {/* Generate hreflang tags for SEO */}
+        {Object.entries(multilingualUrls).map(([lang, url]) => (
+          <link key={lang} rel="alternate" hrefLang={lang} href={url} />
+        ))}
+        <link rel="canonical" href={multilingualUrls[locale]} />
       </Head>
 
-      {/* Additional content */}
+      {/* Page content */}
+      <main>{/* Your page content here */}</main>
     </div>
   );
 };
 
-export const getStaticProps: GetStaticProps = async ({ params }) => {
+export const getStaticProps: GetStaticProps<HomePageProps> = async ({
+  params,
+}) => {
   const locale = params?.locale as string;
 
-  const t = <T,>(content: IConfigLocales<T>) => getTranslation(content, locale);
+  const metadata = getIntlayer("page-metadata", locale);
+
+  /**
+   * Generates an object containing all url for each locale.
+   *
+   * Example:
+   * ```ts
+   *  getMultilingualUrls('/about');
+   *
+   *  // Returns
+   *  // {
+   *  //   en: '/about',
+   *  //   fr: '/fr/about',
+   *  //   es: '/es/about',
+   *  // }
+   * ```
+   */
+  const multilingualUrls = getMultilingualUrls("/");
+
+  return {
+    props: {
+      locale,
+      metadata,
+      multilingualUrls,
+    },
+  };
+};
+
+export default HomePage;
+
+// ... Rest of the code including getStaticPaths
+````
+
+````jsx fileName="src/pages/[locale]/index.mjx" codeFormat="esm"
+import { getIntlayer, getMultilingualUrls } from "intlayer";
+import { useIntlayer } from "next-intlayer";
+import Head from "next/head";
+
+const HomePage = ({ metadata, multilingualUrls, locale }) => {
+  const content = useIntlayer("page");
+
+  return (
+    <div>
+      <Head>
+        <title>{metadata.title}</title>
+        <meta name="description" content={metadata.description} />
+        {/* Generate hreflang tags for SEO */}
+        {Object.entries(multilingualUrls).map(([lang, url]) => (
+          <link key={lang} rel="alternate" hrefLang={lang} href={url} />
+        ))}
+        <link rel="canonical" href={multilingualUrls[locale]} />
+      </Head>
+
+      {/* Page content */}
+      <main>{/* Your page content here */}</main>
+    </div>
+  );
+};
+
+export const getStaticProps = async ({ params }) => {
+  const locale = params?.locale;
+
+  const metadata = getIntlayer("page-metadata", locale);
+
+  /**
+   * Generates an object containing all url for each locale.
+   *
+   * Example:
+   * ```ts
+   *  getMultilingualUrls('/about');
+   *
+   *  // Returns
+   *  // {
+   *  //   en: '/about',
+   *  //   fr: '/fr/about',
+   *  //   es: '/es/about',
+   *  // }
+   * ```
+   */
+  const multilingualUrls = getMultilingualUrls("/");
+
+  return {
+    props: {
+      locale,
+      metadata,
+      multilingualUrls,
+    },
+  };
+};
+
+export default HomePage;
+
+// ... Rest of the code including getStaticPaths
+````
+
+````jsx fileName="src/pages/[locale]/index.csx" codeFormat="commonjs"
+const { getIntlayer, getMultilingualUrls } = require("intlayer");
+const { useIntlayer } = require("next-intlayer");
+const Head = require("next/head");
+
+const HomePage = ({ metadata, multilingualUrls, locale }) => {
+  const content = useIntlayer("page");
+
+  return (
+    <div>
+      <Head>
+        <title>{metadata.title}</title>
+        <meta name="description" content={metadata.description} />
+        {/* Generate hreflang tags for SEO */}
+        {Object.entries(multilingualUrls).map(([lang, url]) => (
+          <link key={lang} rel="alternate" hrefLang={lang} href={url} />
+        ))}
+        <link rel="canonical" href={multilingualUrls[locale]} />
+      </Head>
+
+      {/* Page content */}
+      <main>{/* Your page content here */}</main>
+    </div>
+  );
+};
+
+const getStaticProps = async ({ params }) => {
+  const locale = params?.locale;
+
+  const metadata = getIntlayer("page-metadata", locale);
+
+  /**
+   * Generates an object containing all url for each locale.
+   *
+   * Example:
+   * ```ts
+   *  getMultilingualUrls('/about');
+   *
+   *  // Returns
+   *  // {
+   *  //   en: '/about',
+   *  //   fr: '/fr/about',
+   *  //   es: '/es/about',
+   *  // }
+   * ```
+   */
+  const multilingualUrls = getMultilingualUrls("/");
+
+  return {
+    props: {
+      locale,
+      metadata,
+      multilingualUrls,
+    },
+  };
+};
+
+module.exports = {
+  getStaticProps,
+  getStaticPaths,
+  default: HomePage,
+};
+
+// ... Rest of the code including getStaticPaths
+````
+
+> Note that the `getIntlayer` function imported from `next-intlayer` returns your content wrapped in an `IntlayerNode`, allowing integration with the visual editor. In contrast, the `getIntlayer` function imported from `intlayer` returns your content directly without additional properties.
+
+Alternatively, you can use the `getTranslation` function to declare your metadata. However, using content declaration files is recommended to automate the translation of your metadata and externalize the content at some point.
+
+```tsx fileName="src/pages/[locale]/index.tsx" codeFormat="typescript"
+import { GetStaticPaths, GetStaticProps } from "next";
+import {
+  type IConfigLocales,
+  getTranslation,
+  getMultilingualUrls,
+} from "intlayer";
+import { useIntlayer } from "next-intlayer";
+import Head from "next/head";
+import type { FC } from "react";
+
+interface HomePageProps {
+  locale: string;
+  metadata: {
+    title: string;
+    description: string;
+  };
+  multilingualUrls: Record<string, string>;
+}
+
+const HomePage: FC<HomePageProps> = ({ metadata, multilingualUrls, locale }) => {
+  const content = useIntlayer("page");
+
+  return (
+    <div>
+      <Head>
+        <title>{metadata.title}</title>
+        <meta name="description" content={metadata.description} />
+        {/* Generate hreflang tags for SEO */}
+        {Object.entries(multilingualUrls).map(([lang, url]) => (
+          <link
+            key={lang}
+            rel="alternate"
+            hrefLang={lang}
+            href={url}
+          />
+        ))}
+        <link rel="canonical" href={multilingualUrls[locale]} />
+      </Head>
+
+      {/* Page content */}
+      <main>
+        {/* Your page content here */}
+      </main>
+    </div>
+  );
+};
+
+export const getStaticProps: GetStaticProps<HomePageProps> = async ({
+  params
+}) => {
+  const locale = params?.locale as string;
+  const t = <T>(content: IConfigLocales<T>) => getTranslation(content, locale);
 
   const metadata = {
-    title: t({
-      en: "My Website",
-      fr: "Mon Site Web",
-      es: "Mi Sitio Web",
+    title: t<string>({
+      en: "My title",
+      fr: "Mon titre",
+      es: "Mi título",
     }),
     description: t({
-      en: "Welcome to my website.",
-      fr: "Bienvenue sur mon site Web.",
-      es: "Bienvenido a mi sitio web.",
+      en: "My description",
+      fr: "Ma description",
+      es: "Mi descripción",
     }),
   };
 
+  const multilingualUrls = getMultilingualUrls("/");
+
   return {
     props: {
       locale,
       metadata,
+      multilingualUrls,
     },
   };
 };
@@ -600,49 +926,55 @@ export default HomePage;
 ```
 
 ```jsx fileName="src/pages/[locale]/index.mjx" codeFormat="esm"
-import { GetStaticPaths, GetStaticProps } from "next";
-import { type IConfigLocales, getTranslation, Locales } from "intlayer";
+import { getTranslation, getMultilingualUrls } from "intlayer";
 import { useIntlayer } from "next-intlayer";
+import Head from "next/head";
 
+const HomePage = ({ metadata, multilingualUrls, locale }) => {
+  const content = useIntlayer("page");
 
-
-const HomePage = ({ metadata }) => {
-  // Metadata can be used in the head or other components as needed
   return (
     <div>
       <Head>
         <title>{metadata.title}</title>
         <meta name="description" content={metadata.description} />
+        {/* Generate hreflang tags for SEO */}
+        {Object.entries(multilingualUrls).map(([lang, url]) => (
+          <link key={lang} rel="alternate" hrefLang={lang} href={url} />
+        ))}
+        <link rel="canonical" href={multilingualUrls[locale]} />
       </Head>
 
-      {/* Additional content */}
+      {/* Page content */}
+      <main>{/* Your page content here */}</main>
     </div>
   );
 };
 
 export const getStaticProps = async ({ params }) => {
-  const locale = params?.locale as string;
-
-  const t = (content) =>
-    getTranslation(content, locale);
+  const locale = params?.locale;
+  const t = (content) => getTranslation(content, locale);
 
   const metadata = {
     title: t({
-      en: "My Website",
-      fr: "Mon Site Web",
-      es: "Mi Sitio Web",
+      en: "My title",
+      fr: "Mon titre",
+      es: "Mi título",
     }),
     description: t({
-      en: "Welcome to my website.",
-      fr: "Bienvenue sur mon site Web.",
-      es: "Bienvenido a mi sitio web.",
+      en: "My description",
+      fr: "Ma description",
+      es: "Mi descripción",
     }),
   };
 
+  const multilingualUrls = getMultilingualUrls("/");
+
   return {
     props: {
       locale,
       metadata,
+      multilingualUrls,
     },
   };
 };
@@ -653,48 +985,55 @@ export default HomePage;
 ```
 
 ```jsx fileName="src/pages/[locale]/index.csx" codeFormat="commonjs"
-const { GetStaticPaths, GetStaticProps } = require("next");
-const { type IConfigLocales, getTranslation, Locales } = require("intlayer");
+const { getTranslation, getMultilingualUrls } = require("intlayer");
 const { useIntlayer } = require("next-intlayer");
+const Head = require("next/head");
 
+const HomePage = ({ metadata, multilingualUrls, locale }) => {
+  const content = useIntlayer("page");
 
-const HomePage = ({ metadata }) => {
-  // Metadata can be used in the head or other components as needed
   return (
     <div>
       <Head>
         <title>{metadata.title}</title>
         <meta name="description" content={metadata.description} />
+        {/* Generate hreflang tags for SEO */}
+        {Object.entries(multilingualUrls).map(([lang, url]) => (
+          <link key={lang} rel="alternate" hrefLang={lang} href={url} />
+        ))}
+        <link rel="canonical" href={multilingualUrls[locale]} />
       </Head>
 
-      {/* Additional content */}
+      {/* Page content */}
+      <main>{/* Your page content here */}</main>
     </div>
   );
 };
 
 const getStaticProps = async ({ params }) => {
   const locale = params?.locale;
-
-  const t = (content) =>
-    getTranslation(content, locale);
+  const t = (content) => getTranslation(content, locale);
 
   const metadata = {
     title: t({
-      en: "My Website",
-      fr: "Mon Site Web",
-      es: "Mi Sitio Web",
+      en: "My title",
+      fr: "Mon titre",
+      es: "Mi título",
     }),
     description: t({
-      en: "Welcome to my website.",
-      fr: "Bienvenue sur mon site Web.",
-      es: "Bienvenido a mi sitio web.",
+      en: "My description",
+      fr: "Ma description",
+      es: "Mi descripción",
     }),
   };
 
+  const multilingualUrls = getMultilingualUrls("/");
+
   return {
     props: {
       locale,
       metadata,
+      multilingualUrls,
     },
   };
 };
@@ -708,7 +1047,9 @@ module.exports = {
 // ... Rest of the code including getStaticPaths
 ```
 
-### (Optional) Step 9: Change the Language of Your Content
+> Learn more about the metadata optimization [on the official Next.js documentation](https://nextjs.org/docs/pages/building-your-application/optimizing/metadata).
+
+### (Optional) Step 9: Change the language of your content
 
 To change the language of your content in Next.js, the recommended way is to use the `Link` component to redirect users to the appropriate localized page. The `Link` component enables prefetching of the page, which helps avoid a full page reload.
 
@@ -889,19 +1230,13 @@ return (
 > The `useLocalePageRouter` API is the same as `useLocale`. To Learn more about the `useLocale` hook, refer to the [documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/next-intlayer/useLocale.md).
 
 > Documentation references:
-
+>
 > - [`getLocaleName` hook](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/intlayer/getLocaleName.md)
-
 > - [`getLocalizedUrl` hook](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/intlayer/getLocalizedUrl.md)
-
 > - [`getHTMLTextDir` hook](https://github.com/aymericzip/intlayer/blob/main/docs/en/packages/intlayer/getHTMLTextDir.md)
-
 > - [`hrefLang` attribute](https://developers.google.com/search/docs/specialty/international/localized-versions?hl=fr)
-
 > - [`lang` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang)
-
 > - [`dir` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir)
-
 > - [`aria-current` attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current)
 
 ### (Optional) Step 10: Creating a Localized Link Component