@intlayer/docs 5.5.8

package/es/intlayer_with_nextjs_page_router.md

@@ -0,0 +1,1088 @@
+# Comenzando con la Internacionalización (i18n) con Intlayer y Next.js usando Page Router
+
+## ¿Qué es Intlayer?
+
+**Intlayer** es una biblioteca innovadora y de código abierto para la internacionalización (i18n) diseñada para simplificar el soporte multilingüe en aplicaciones web modernas. Intlayer se integra perfectamente con el último framework **Next.js**, incluyendo su tradicional **Page Router**.
+
+Con Intlayer, puedes:
+
+- **Gestionar fácilmente las traducciones** utilizando diccionarios declarativos a nivel de componente.
+- **Localizar dinámicamente metadatos**, rutas y contenido.
+- **Garantizar soporte para TypeScript** con tipos autogenerados, mejorando la autocompletación y la detección de errores.
+- **Beneficiarte de características avanzadas**, como la detección y cambio dinámico de locales.
+
+> Intlayer es compatible con Next.js 12, 13, 14 y 15. Si estás utilizando Next.js App Router, consulta la [guía de App Router](https://github.com/aymericzip/intlayer/blob/main/docs/es/intlayer_with_nextjs_14.md). Para Next.js 15, sigue esta [guía](https://github.com/aymericzip/intlayer/blob/main/docs/es/intlayer_with_nextjs_15.md).
+
+---
+
+## Guía Paso a Paso para Configurar Intlayer en una Aplicación Next.js Usando Page Router
+
+### Paso 1: Instalar Dependencias
+
+Instala los paquetes necesarios utilizando tu gestor de paquetes preferido:
+
+```bash packageManager="npm"
+npm install intlayer next-intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add intlayer next-intlayer
+```
+
+```bash packageManager="yarn"
+yarn add intlayer next-intlayer
+```
+
+- **intlayer**
+
+  El paquete principal que proporciona herramientas de internacionalización para la gestión de configuraciones, traducciones, [declaración de contenido](https://github.com/aymericzip/intlayer/blob/main/docs/es/dictionary/get_started.md), transpilación y [comandos CLI](https://github.com/aymericzip/intlayer/blob/main/docs/es/intlayer_cli.md).
+
+- **next-intlayer**
+
+  El paquete que integra Intlayer con Next.js. Proporciona proveedores de contexto y hooks para la internacionalización en Next.js. Además, incluye el plugin de Next.js para integrar Intlayer con [Webpack](https://webpack.js.org/) o [Turbopack](https://nextjs.org/docs/app/api-reference/turbopack), así como middleware para detectar el idioma preferido del usuario, gestionar cookies y manejar redirecciones de URL.
+
+### Paso 2: Configurar Tu Proyecto
+
+Crea un archivo de configuración para definir los idiomas soportados por tu aplicación:
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+// Configuración de idiomas soportados
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // Agrega tus otros locales aquí
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+// Configuración de idiomas soportados
+import { Locales } from "intlayer";
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // Agrega tus otros locales aquí
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+// Configuración de idiomas soportados
+const { Locales } = require("intlayer");
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.SPANISH,
+      // Agrega tus otros locales aquí
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+module.exports = config;
+```
+
+> A través de este archivo de configuración, puedes configurar URLs localizadas, redirección de middleware, nombres de cookies, la ubicación y extensión de tus declaraciones de contenido, desactivar los logs de Intlayer en la consola, y más. Para una lista completa de parámetros disponibles, consulta la [documentación de configuración](https://github.com/aymericzip/intlayer/blob/main/docs/es/configuration.md).
+
+### Paso 3: Integrar Intlayer con la Configuración de Next.js
+
+Modifica tu configuración de Next.js para incorporar Intlayer:
+
+```typescript fileName="next.config.mjs"
+import { withIntlayer } from "next-intlayer/server";
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  // Tu configuración existente de Next.js
+};
+
+export default withIntlayer(nextConfig);
+```
+
+> El plugin `withIntlayer()` de Next.js se utiliza para integrar Intlayer con Next.js. Garantiza la construcción de archivos de declaración de contenido y los monitorea en modo de desarrollo. Define variables de entorno de Intlayer dentro de los entornos de [Webpack](https://webpack.js.org/) o [Turbopack](https://nextjs.org/docs/app/api-reference/turbopack). Además, proporciona alias para optimizar el rendimiento y garantizar la compatibilidad con componentes del servidor.
+
+### Paso 4: Configurar Middleware para la Detección de Locales
+
+Configura middleware para detectar y manejar automáticamente el idioma preferido del usuario:
+
+```typescript fileName="src/middleware.ts" codeFormat="typescript"
+export { intlayerMiddleware as middleware } from "next-intlayer/middleware";
+
+export const config = {
+  matcher:
+    "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",
+};
+```
+
+```javascript fileName="src/middleware.mjs" codeFormat="esm"
+export { intlayerMiddleware as middleware } from "next-intlayer/middleware";
+
+export const config = {
+  matcher:
+    "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",
+};
+```
+
+```javascript fileName="src/middleware.cjs" codeFormat="commonjs"
+const { intlayerMiddleware } = require("next-intlayer/middleware");
+
+const config = {
+  matcher:
+    "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",
+};
+
+module.exports = { middleware: intlayerMiddleware, config };
+```
+
+> Adapta el parámetro `matcher` para que coincida con las rutas de tu aplicación. Para más detalles, consulta la [documentación de Next.js sobre la configuración del matcher](https://nextjs.org/docs/app/building-your-application/routing/middleware).
+
+### Paso 5: Definir Rutas Dinámicas de Locales
+
+Implementa enrutamiento dinámico para servir contenido localizado basado en el idioma del usuario.
+
+1.  **Crear Páginas Específicas por Idioma:**
+
+    Renombra tu archivo de página principal para incluir el segmento dinámico `[locale]`.
+
+    ```bash
+    mv src/pages/index.tsx src/pages/[locale]/index.tsx
+    ```
+
+2.  **Actualizar `_app.tsx` para Manejar la Localización:**
+
+    Modifica tu `_app.tsx` para incluir proveedores de Intlayer.
+
+    ```tsx fileName="src/pages/_app.tsx" codeFormat="typescript"
+    import type { FC } from "react";
+    import type { AppProps } from "next/app";
+    import { IntlayerClientProvider } from "next-intlayer";
+
+    const App = FC<AppProps>({ Component, pageProps }) => {
+      const { locale } = pageProps;
+
+      return (
+        <IntlayerClientProvider locale={locale}>
+          <Component {...pageProps} />
+        </IntlayerClientProvider>
+      );
+    }
+
+    export default MyApp;
+    ```
+
+    ```jsx fileName="src/pages/_app.mjx" codeFormat="esm"
+    import { IntlayerClientProvider } from "next-intlayer";
+
+    const App = ({ Component, pageProps }) => (
+      <IntlayerClientProvider locale={locale}>
+        <Component {...pageProps} />
+      </IntlayerClientProvider>
+    );
+
+    export default App;
+    ```
+
+    ```jsx fileName="src/pages/_app.csx" codeFormat="commonjs"
+    const { IntlayerClientProvider } = require("next-intlayer");
+
+    const App = ({ Component, pageProps }) => (
+      <IntlayerClientProvider locale={locale}>
+        <Component {...pageProps} />
+      </IntlayerClientProvider>
+    );
+
+    module.exports = App;
+    ```
+
+3.  **Configurar `getStaticPaths` y `getStaticProps`:**
+
+    En tu `[locale]/index.tsx`, define las rutas y propiedades para manejar diferentes idiomas.
+
+    ```tsx fileName="src/pages/[locale]/index.tsx" codeFormat="typescript"
+    import type { FC } from "react";
+    import type { GetStaticPaths, GetStaticProps } from "next";
+    import { type Locales, getConfiguration } from "intlayer";
+
+    const HomePage: FC = () => <div>{/* Tu contenido aquí */}</div>;
+
+    export const getStaticPaths: GetStaticPaths = () => {
+      const { internationalization } = getConfiguration();
+      const { locales } = internationalization;
+
+      const paths = locales.map((locale) => ({
+        params: { locale },
+      }));
+
+      return { paths, fallback: false };
+    };
+
+    export const getStaticProps: GetStaticProps = ({ params }) => {
+      const locale = params?.locale as string;
+
+      return {
+        props: {
+          locale,
+        },
+      };
+    };
+
+    export default HomePage;
+    ```
+
+    ```jsx fileName="src/pages/[locale]/index.mjx" codeFormat="esm"
+    import { getConfiguration } from "intlayer";
+    import { ComponentExample } from "@components/ComponentExample";
+
+    const HomePage = () => <div>{/* Tu contenido aquí */}</div>;
+
+    export const getStaticPaths = () => {
+      const { internationalization } = getConfiguration();
+      const { locales } = internationalization;
+
+      const paths = locales.map((locale) => ({
+        params: { locale },
+      }));
+
+      return { paths, fallback: false };
+    };
+
+    export const getStaticProps = ({ params }) => {
+      const locale = params?.locale;
+
+      return {
+        props: {
+          locale,
+        },
+      };
+    };
+    ```
+
+    ```jsx fileName="src/pages/[locale]/index.csx" codeFormat="commonjs"
+    const { getConfiguration } = require("intlayer");
+    const { ComponentExample } = require("@components/ComponentExample");
+
+    const HomePage = () => <div>{/* Tu contenido aquí */}</div>;
+
+    const getStaticPaths = async () => {
+      const { internationalization } = getConfiguration();
+      const { locales } = internationalization;
+
+      const paths = locales.map((locale) => ({
+        params: { locale },
+      }));
+
+      return { paths, fallback: false };
+    };
+
+    const getStaticProps = async ({ params }) => {
+      const locale = params?.locale;
+
+      return {
+        props: {
+          locale,
+        },
+      };
+    };
+
+    module.exports = {
+      getStaticProps,
+      getStaticPaths,
+      default: HomePage,
+    };
+    ```
+
+> `getStaticPaths` y `getStaticProps` aseguran que tu aplicación preconstruya las páginas necesarias para todos los idiomas en el Page Router de Next.js. Este enfoque reduce el cálculo en tiempo de ejecución y mejora la experiencia del usuario. Para más detalles, consulta la documentación de Next.js sobre [`getStaticPaths`](https://nextjs.org/docs/pages/building-your-application/data-fetching/get-static-paths) y [`getStaticProps`](https://nextjs.org/docs/pages/building-your-application/data-fetching/get-static-props).
+
+### Paso 6: Declarar Tu Contenido
+
+Crea y gestiona tus declaraciones de contenido para almacenar traducciones.
+
+```tsx fileName="src/pages/[locale]/home.content.ts" contentDeclarationFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const homeContent = {
+  key: "home",
+  content: {
+    title: t({
+      en: "Welcome to My Website",
+      fr: "Bienvenue sur mon site Web",
+      es: "Bienvenido a mi sitio web",
+    }),
+    description: t({
+      en: "Get started by editing this page.",
+      fr: "Commencez par éditer cette page.",
+      es: "Comience por editar esta página.",
+    }),
+  },
+} satisfies Dictionary;
+
+export default homeContent;
+```
+
+```javascript fileName="src/pages/[locale]/home.content.mjs" contentDeclarationFormat="esm"
+import { t } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const homeContent = {
+  key: "home",
+  content: {
+    getStarted: {
+      main: t({
+        en: "Get started by editing this page.",
+        fr: "Commencez par éditer cette page.",
+        es: "Comience por editar esta página.",
+      }),
+      pageLink: "src/app/page.tsx",
+    },
+  },
+};
+
+export default homeContent;
+```
+
+```javascript fileName="src/pages/[locale]/home.content.cjs" contentDeclarationFormat="commonjs"
+const { t } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const homeContent = {
+  key: "home",
+  content: {
+    getStarted: {
+      main: t({
+        en: "Get started by editing this page.",
+        fr: "Commencez par éditer cette page.",
+        es: "Comience por editar esta página.",
+      }),
+      pageLink: "src/app/page.tsx",
+    },
+  },
+};
+
+module.exports = homeContent;
+```
+
+```json fileName="src/pages/[locale]/home.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "home",
+  "content": {
+    "getStarted": {
+      "nodeType": "translation",
+      "translation": {
+        "en": "Get started by editing this page.",
+        "fr": "Commencez par éditer cette page.",
+        "es": "Comience por editar esta página."
+      }
+    },
+    "pageLink": {
+      "nodeType": "translation",
+      "translation": {
+        "en": "src/app/page.tsx",
+        "fr": "src/app/page.tsx",
+        "es": "src/app/page.tsx"
+      }
+    }
+  }
+}
+```
+
+Para más información sobre cómo declarar contenido, consulta la [guía de declaración de contenido](https://github.com/aymericzip/intlayer/blob/main/docs/es/dictionary/get_started.md).
+
+### Paso 7: Utilizar Contenido en Tu Código
+
+Accede a tus diccionarios de contenido en toda tu aplicación para mostrar contenido traducido.
+
+```tsx {2,6} fileName="src/pages/[locale]/index.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useIntlayer } from "next-intlayer";
+import { ComponentExample } from "@components/ComponentExample";
+
+const HomePage: FC = () => {
+  const content = useIntlayer("home");
+
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+      <ComponentExample />
+      {/* Componentes adicionales */}
+    </div>
+  );
+};
+
+// ... Resto del código, incluyendo getStaticPaths y getStaticProps
+
+export default HomePage;
+```
+
+```jsx {1,5} fileName="src/pages/[locale]/index.mjx" codeFormat="esm"
+import { useIntlayer } from "next-intlayer";
+import { ComponentExample } from "@components/ComponentExample";
+
+const HomePage = () => {
+  const content = useIntlayer("home");
+
+  return (
+    <div>
+      <h1>{content.getStarted.main}</h1>
+      <code>{content.getStarted.pageLink}</code>
+
+      <ComponentExample />
+      {/* Componentes adicionales */}
+    </div>
+  );
+};
+
+// ... Resto del código, incluyendo getStaticPaths y getStaticProps
+
+export default HomePage;
+```
+
+```jsx {1,5} fileName="src/pages/[locale]/index.csx" codeFormat="commonjs"
+const { useIntlayer } = require("next-intlayer");
+const { ComponentExample } = require("@components/ComponentExample");
+
+const HomePage = () => {
+  const content = useIntlayer("home");
+
+  return (
+    <div>
+      <h1>{content.getStarted.main}</h1>
+      <code>{content.getStarted.pageLink}</code>
+
+      <ComponentExample />
+      {/* Componentes adicionales */}
+    </div>
+  );
+};
+
+// ... Resto del código, incluyendo getStaticPaths y getStaticProps
+```
+
+```tsx fileName="src/components/ComponentExample.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useIntlayer } from "next-intlayer";
+
+export const ComponentExample: FC = () => {
+  const content = useIntlayer("component-example"); // Asegúrate de tener una declaración de contenido correspondiente
+
+  return (
+    <div>
+      <h2>{content.title}</h2>
+      <p>{content.content}</p>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ComponentExample.mjx" codeFormat="esm"
+import { useIntlayer } from "next-intlayer";
+
+const ComponentExample = () => {
+  const content = useIntlayer("component-example"); // Asegúrate de tener una declaración de contenido correspondiente
+
+  return (
+    <div>
+      <h2>{content.title}</h2>
+      <p>{content.content}</p>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ComponentExample.csx" codeFormat="commonjs"
+const { useIntlayer } = require("next-intlayer");
+
+const ComponentExample = () => {
+  const content = useIntlayer("component-example"); // Asegúrate de tener una declaración de contenido correspondiente
+
+  return (
+    <div>
+      <h2>{content.title}</h2>
+      <p>{content.content}</p>
+    </div>
+  );
+};
+```
+
+> Al usar traducciones en atributos de tipo `string` (por ejemplo, `alt`, `title`, `href`, `aria-label`), llama al valor de la función de la siguiente manera:
+
+> ```jsx
+>
+> ```
+
+> <img src={content.image.src.value} alt={content.image.value} />
+
+> ```
+>
+> ```
+
+> Para aprender más sobre el hook `useIntlayer`, consulta la [documentación](https://github.com/aymericzip/intlayer/blob/main/docs/es/packages/next-intlayer/useIntlayer.md).
+
+### (Opcional) Paso 8: Internacionalizar Tus Metadatos
+
+Para internacionalizar metadatos como títulos y descripciones de páginas, utiliza la función `getStaticProps` junto con la función `getTranslation` de Intlayer.
+
+```tsx fileName="src/pages/[locale]/index.tsx" codeFormat="typescript"
+import { GetStaticPaths, GetStaticProps } from "next";
+import { type IConfigLocales, getTranslation, Locales } from "intlayer";
+import { useIntlayer } from "next-intlayer";
+
+interface HomePageProps {
+  locale: string;
+  metadata: Metadata;
+}
+
+const HomePage = ({ metadata }: HomePageProps) => {
+  // Los metadatos pueden ser utilizados en el head u otros componentes según sea necesario
+  return (
+    <div>
+      <Head>
+        <title>{metadata.title}</title>
+        <meta name="description" content={metadata.description} />
+      </Head>
+
+      {/* Contenido adicional */}
+    </div>
+  );
+};
+
+export const getStaticProps: GetStaticProps = 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",
+    }),
+    description: t({
+      en: "Welcome to my website.",
+      fr: "Bienvenue sur mon site Web.",
+      es: "Bienvenido a mi sitio web.",
+    }),
+  };
+
+  return {
+    props: {
+      locale,
+      metadata,
+    },
+  };
+};
+
+export default HomePage;
+
+// ... Resto del código incluyendo getStaticPaths
+```
+
+```jsx fileName="src/pages/[locale]/index.mjx" codeFormat="esm"
+import { GetStaticPaths, GetStaticProps } from "next";
+import { type IConfigLocales, getTranslation, Locales } from "intlayer";
+import { useIntlayer } from "next-intlayer";
+
+
+
+const HomePage = ({ metadata }) => {
+  // Los metadatos pueden ser utilizados en el head u otros componentes según sea necesario
+  return (
+    <div>
+      <Head>
+        <title>{metadata.title}</title>
+        <meta name="description" content={metadata.description} />
+      </Head>
+
+      {/* Contenido adicional */}
+    </div>
+  );
+};
+
+export const getStaticProps = async ({ params }) => {
+  const locale = params?.locale as string;
+
+  const t = (content) =>
+    getTranslation(content, locale);
+
+  const metadata = {
+    title: t({
+      en: "My Website",
+      fr: "Mon Site Web",
+      es: "Mi Sitio Web",
+    }),
+    description: t({
+      en: "Welcome to my website.",
+      fr: "Bienvenue sur mon site Web.",
+      es: "Bienvenido a mi sitio web.",
+    }),
+  };
+
+  return {
+    props: {
+      locale,
+      metadata,
+    },
+  };
+};
+
+export default HomePage;
+
+// ... Resto del código incluyendo getStaticPaths
+```
+
+```jsx fileName="src/pages/[locale]/index.csx" codeFormat="commonjs"
+const { GetStaticPaths, GetStaticProps } = require("next");
+const { type IConfigLocales, getTranslation, Locales } = require("intlayer");
+const { useIntlayer } = require("next-intlayer");
+
+
+const HomePage = ({ metadata }) => {
+  // Los metadatos pueden ser utilizados en el head u otros componentes según sea necesario
+  return (
+    <div>
+      <Head>
+        <title>{metadata.title}</title>
+        <meta name="description" content={metadata.description} />
+      </Head>
+
+      {/* Contenido adicional */}
+    </div>
+  );
+};
+
+const getStaticProps = async ({ params }) => {
+  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",
+    }),
+    description: t({
+      en: "Welcome to my website.",
+      fr: "Bienvenue sur mon site Web.",
+      es: "Bienvenido a mi sitio web.",
+    }),
+  };
+
+  return {
+    props: {
+      locale,
+      metadata,
+    },
+  };
+};
+
+module.exports = {
+  getStaticProps,
+  getStaticPaths,
+  default: HomePage,
+};
+
+// ... Resto del código incluyendo getStaticPaths
+```
+
+### (Opcional) Paso 9: Cambiar el Idioma de Tu Contenido
+
+Para permitir que los usuarios cambien de idioma dinámicamente, utiliza la función `setLocale` proporcionada por el hook `useLocale`.
+
+```tsx fileName="src/components/LanguageSwitcher.tsx" codeFormat="typescript"
+import {
+  Locales,
+  getHTMLTextDir,
+  getLocaleName,
+  getLocalizedUrl,
+} from "intlayer";
+import { useLocalePageRouter } from "next-intlayer";
+import { type FC } from "react";
+import Link from "next/link";
+
+const LocaleSwitcher: FC = () => {
+  const { locale, pathWithoutLocale, availableLocales, setLocale } =
+    useLocalePageRouter();
+
+  return (
+    <div>
+      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>
+      <div id="localePopover" popover="auto">
+        {availableLocales.map((localeItem) => (
+          <Link
+            href={getLocalizedUrl(pathWithoutLocale, localeItem)}
+            hrefLang={localeItem}
+            key={localeItem}
+            aria-current={locale === localeItem ? "page" : undefined}
+            onClick={() => setLocaleCookie(localeItem)}
+          >
+            <span>
+              {/* Locale - e.g. FR */}
+              {localeItem}
+            </span>
+            <span>
+              {/* Idioma en su propio Local - e.g. Français */}
+              {getLocaleName(localeItem, locale)}
+            </span>
+            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
+              {/* Idioma en el Local actual - e.g. Francés con el local actual configurado en Locales.SPANISH */}
+              {getLocaleName(localeItem)}
+            </span>
+            <span dir="ltr" lang={Locales.ENGLISH}>
+              {/* Idioma en Inglés - e.g. French */}
+              {getLocaleName(localeItem, Locales.ENGLISH)}
+            </span>
+          </Link>
+        ))}
+      </div>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/LanguageSwitcher.msx" codeFormat="esm"
+import {
+  Locales,
+  getHTMLTextDir,
+  getLocaleName,
+  getLocalizedUrl,
+} from "intlayer";
+import { useLocalePageRouter } from "next-intlayer";
+
+const LocaleSwitcher = () => {
+  const { locale, pathWithoutLocale, availableLocales, setLocale } =
+    useLocalePageRouter();
+
+  return (
+    <div>
+      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>
+      <div id="localePopover" popover="auto">
+        {availableLocales.map((localeItem) => (
+          <Link
+            href={getLocalizedUrl(pathWithoutLocale, localeItem)}
+            hrefLang={localeItem}
+            key={localeItem}
+            aria-current={locale === localeItem ? "page" : undefined}
+            onClick={() => setLocaleCookie(localeItem)}
+          >
+            <span>
+              {/* Locale - e.g. FR */}
+              {localeItem}
+            </span>
+            <span>
+              {/* Idioma en su propio Local - e.g. Français */}
+              {getLocaleName(localeItem, locale)}
+            </span>
+            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
+              {/* Idioma en el Local actual - e.g. Francés con el local actual configurado en Locales.SPANISH */}
+              {getLocaleName(localeItem)}
+            </span>
+            <span dir="ltr" lang={Locales.ENGLISH}>
+              {/* Idioma en Inglés - e.g. French */}
+              {getLocaleName(localeItem, Locales.ENGLISH)}
+            </span>
+          </Link>
+        ))}
+      </div>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/LanguageSwitcher.msx" codeFormat="commonjs"
+const {
+  Locales,
+  getHTMLTextDir,
+  getLocaleName,
+  getLocalizedUrl,
+} = require("intlayer");
+const { useLocalePageRouter } = require("next-intlayer");
+
+const LocaleSwitcher = () => {
+  const { locale, pathWithoutLocale, availableLocales, setLocale } =
+    useLocalePageRouter();
+
+  return (
+    <select>
+      {availableLocales.map((localeItem) => (
+        <option value={localeItem} key={localeItem}>
+          <a
+            href={getLocalizedUrl(pathWithoutLocale, localeItem)}
+            hrefLang={localeItem}
+            aria-current={locale === localeItem ? "page" : undefined}
+            onClick={(e) => {
+              e.preventDefault();
+              setLocale(localeItem);
+            }}
+          >
+            <span>
+              {/* Locale - e.g. FR */}
+              {localeItem}
+            </span>
+            <span>
+              {/* Idioma en su propio Local - e.g. Français */}
+              {getLocaleName(localeItem, locale)}
+            </span>
+            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
+              {/* Idioma en el Local actual - e.g. Francés con el local actual configurado en Locales.SPANISH */}
+              {getLocaleName(localeItem)}
+            </span>
+            <span dir="ltr" lang={Locales.ENGLISH}>
+              {/* Idioma en Inglés - e.g. French */}
+              {getLocaleName(localeItem, Locales.ENGLISH)}
+            </span>
+          </a>
+        </option>
+      ))}
+    </select>
+  );
+};
+```
+
+> La API `useLocalePageRouter` es la misma que `useLocale`. Para aprender más sobre el hook `useLocale`, consulta la [documentación](https://github.com/aymericzip/intlayer/blob/main/docs/es/packages/next-intlayer/useLocale.md).
+
+> Referencias de la documentación:
+
+> - [`getLocaleName` hook](https://github.com/aymericzip/intlayer/blob/main/docs/es/packages/intlayer/getLocaleName.md)
+
+> - [`getLocalizedUrl` hook](https://github.com/aymericzip/intlayer/blob/main/docs/es/packages/intlayer/getLocalizedUrl.md)
+
+> - [`getHTMLTextDir` hook](https://github.com/aymericzip/intlayer/blob/main/docs/es/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)
+
+### (Opcional) Paso 10: Crear un Componente de Enlace Localizado
+
+Para cambiar el idioma de tu contenido en Next.js, la forma recomendada es usar el componente `Link` para redirigir a los usuarios a la página localizada apropiada. El componente `Link` permite la precarga de la página, lo que ayuda a evitar una recarga completa de la página.
+
+Este comportamiento es útil por varias razones:
+
+- **SEO y Experiencia de Usuario**: Las URLs localizadas ayudan a los motores de búsqueda a indexar correctamente las páginas específicas por idioma y proporcionan a los usuarios contenido en su idioma preferido.
+- **Consistencia**: Al usar un enlace localizado en toda tu aplicación, garantizas que la navegación se mantenga dentro del idioma actual, evitando cambios inesperados de idioma.
+- **Mantenibilidad**: Centralizar la lógica de localización en un único componente simplifica la gestión de URLs, haciendo que tu base de código sea más fácil de mantener y ampliar a medida que tu aplicación crece.
+
+A continuación, se muestra la implementación de un componente `Link` localizado en TypeScript:
+
+```tsx fileName="src/components/Link.tsx" codeFormat="typescript"
+"use client";
+
+import { getLocalizedUrl } from "intlayer";
+import NextLink, { type LinkProps as NextLinkProps } from "next/link";
+import { useLocale } from "next-intlayer";
+import { forwardRef, PropsWithChildren, type ForwardedRef } from "react";
+
+/**
+ * Función de utilidad para verificar si una URL es externa.
+ * Si la URL comienza con http:// o https://, se considera externa.
+ */
+export const checkIsExternalLink = (href?: string): boolean =>
+  /^https?:\/\//.test(href ?? "");
+
+/**
+ * Un componente de enlace personalizado que adapta el atributo href según el idioma actual.
+ * Para enlaces internos, utiliza `getLocalizedUrl` para agregar el prefijo del idioma a la URL (por ejemplo, /fr/about).
+ * Esto garantiza que la navegación se mantenga dentro del contexto del idioma actual.
+ */
+export const Link = forwardRef<
+  HTMLAnchorElement,
+  PropsWithChildren<NextLinkProps>
+>(({ href, children, ...props }, ref: ForwardedRef<HTMLAnchorElement>) => {
+  const { locale } = useLocale();
+  const isExternalLink = checkIsExternalLink(href.toString());
+
+  // Si el enlace es interno y se proporciona un href válido, obtiene la URL localizada.
+  const hrefI18n: NextLinkProps["href"] =
+    href && !isExternalLink ? getLocalizedUrl(href.toString(), locale) : href;
+
+  return (
+    <NextLink href={hrefI18n} ref={ref} {...props}>
+      {children}
+    </NextLink>
+  );
+});
+
+Link.displayName = "Link";
+```
+
+```jsx fileName="src/components/Link.mjx" codeFormat="esm"
+'use client';
+
+import { getLocalizedUrl } from 'intlayer';
+import NextLink, { type LinkProps as NextLinkProps } from 'next/link';
+import { useLocale } from 'next-intlayer';
+import { forwardRef, PropsWithChildren, type ForwardedRef } from 'react';
+
+/**
+ * Función de utilidad para verificar si una URL es externa.
+ * Si la URL comienza con http:// o https://, se considera externa.
+ */
+export const checkIsExternalLink = (href) =>
+  /^https?:\/\//.test(href ?? '');
+
+/**
+ * Un componente de enlace personalizado que adapta el atributo href según el idioma actual.
+ * Para enlaces internos, utiliza `getLocalizedUrl` para agregar el prefijo del idioma a la URL (por ejemplo, /fr/about).
+ * Esto garantiza que la navegación se mantenga dentro del contexto del idioma actual.
+ */
+export const Link = forwardRef(({ href, children, ...props }, ref) => {
+  const { locale } = useLocale();
+  const isExternalLink = checkIsExternalLink(href.toString());
+
+  // Si el enlace es interno y se proporciona un href válido, obtiene la URL localizada.
+  const hrefI18n =
+    href && !isExternalLink ? getLocalizedUrl(href.toString(), locale) : href;
+
+  return (
+    <NextLink href={hrefI18n} ref={ref} {...props}>
+      {children}
+    </NextLink>
+  );
+});
+
+Link.displayName = 'Link';
+```
+
+```jsx fileName="src/components/Link.csx" codeFormat="commonjs"
+'use client';
+
+const { getLocalizedUrl } = require("intlayer");
+const NextLink = require("next/link");
+const { useLocale } = require("next-intlayer");
+const { forwardRef } = require("react");
+
+/**
+ * Función de utilidad para verificar si una URL es externa.
+ * Si la URL comienza con http:// o https://, se considera externa.
+ */
+const checkIsExternalLink = (href) =>
+  /^https?:\/\//.test(href ?? '');
+
+
+const Link = forwardRef(({ href, children, ...props }, ref) => {
+  const { locale } = useLocale();
+  const isExternalLink = checkIsExternalLink(href.toString());
+
+  // Si el enlace es interno y se proporciona un href válido, obtiene la URL localizada.
+  const hrefI18n: NextLinkProps['href'] =
+    href && !isExternalLink ? getLocalizedUrl(href.toString(), locale) : href;
+
+  return (
+    <NextLink href={hrefI18n} ref={ref} {...props}>
+      {children}
+    </NextLink>
+  );
+});
+
+Link.displayName = 'Link';
+```
+
+#### Cómo Funciona
+
+- **Detección de Enlaces Externos**:  
+  La función auxiliar `checkIsExternalLink` determina si una URL es externa. Los enlaces externos se dejan sin cambios porque no necesitan localización.
+
+- **Recuperación del Idioma Actual**:  
+  El hook `useLocale` proporciona el idioma actual (por ejemplo, `fr` para francés).
+
+- **Localización de la URL**:  
+  Para enlaces internos (es decir, no externos), se utiliza `getLocalizedUrl` para agregar automáticamente el prefijo del idioma actual a la URL. Esto significa que si tu usuario está en francés, pasar `/about` como el `href` lo transformará en `/fr/about`.
+
+- **Devolución del Enlace**:  
+  El componente devuelve un elemento `<a>` con la URL localizada, asegurando que la navegación sea consistente con el idioma.
+
+Al integrar este componente `Link` en toda tu aplicación, mantienes una experiencia de usuario coherente y consciente del idioma, además de beneficiarte de un mejor SEO y usabilidad.
+
+### (Opcional) Paso 11: Optimiza el tamaño de tu bundle
+
+Cuando usas `next-intlayer`, los diccionarios se incluyen en el bundle de cada página por defecto. Para optimizar el tamaño de tu bundle, Intlayer ofrece un plugin SWC opcional que reemplaza de forma inteligente las llamadas a `useIntlayer` usando macros. Esto asegura que los diccionarios solo se incluyan en los bundles de las páginas que realmente los utilizan.
+
+Para habilitar esta optimización, instala el paquete `@intlayer/swc`. Una vez instalado, `next-intlayer` lo detectará y lo usará automáticamente:
+
+```bash packageManager="npm"
+npm install @intlayer/swc --save-dev
+```
+
+```bash packageManager="pnpm"
+pnpm add @intlayer/swc --save-dev
+```
+
+```bash packageManager="yarn"
+yarn add @intlayer/swc --save-dev
+```
+
+> Nota: Esta optimización solo está disponible para Next.js 13 y superior.
+
+> Nota: Este paquete no se instala por defecto porque los plugins SWC aún son experimentales en Next.js. Puede cambiar en el futuro.
+
+### Configurar TypeScript
+
+Intlayer utiliza la ampliación de módulos para obtener beneficios de TypeScript y fortalecer tu base de código.
+
+![alt text](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png)
+
+![alt text](https://github.com/aymericzip/intlayer/blob/main/docs/assets/translation_error.png)
+
+Asegúrate de que tu configuración de TypeScript incluya los tipos autogenerados.
+
+```json5 fileName="tsconfig.json"
+{
+  // ... Tus configuraciones existentes de TypeScript
+  "include": [
+    // ... Tus configuraciones existentes de TypeScript
+    ".intlayer/**/*.ts", // Incluye los tipos autogenerados
+  ],
+}
+```
+
+### Configuración de Git
+
+Para mantener tu repositorio limpio y evitar cometer archivos generados, se recomienda ignorar los archivos creados por Intlayer.
+
+Agrega las siguientes líneas a tu archivo `.gitignore`:
+
+```plaintext fileName=".gitignore"
+# Ignorar los archivos generados por Intlayer
+.intlayer
+```
+
+## Recursos Adicionales
+
+- **Documentación de Intlayer:** [Repositorio de GitHub](https://github.com/aymericzip/intlayer)
+- **Guía de Diccionario:** [Diccionario](https://github.com/aymericzip/intlayer/blob/main/docs/es/dictionary/get_started.md)
+- **Documentación de Configuración:** [Guía de Configuración](https://github.com/aymericzip/intlayer/blob/main/docs/es/configuration.md)
+
+Siguiendo esta guía, puedes integrar eficazmente Intlayer en tu aplicación Next.js utilizando el Page Router, habilitando un soporte de internacionalización robusto y escalable para tus proyectos web.
+
+### Ir Más Allá
+
+Para ir más allá, puedes implementar el [editor visual](https://github.com/aymericzip/intlayer/blob/main/docs/es/intlayer_visual_editor.md) o externalizar tu contenido utilizando el [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/es/intlayer_CMS.md).