@intlayer/docs 7.0.3 → 7.0.4

package/blog/es/intlayer_with_next-i18next.md

@@ -1,367 +1,142 @@
 ---
 createdAt: 2025-08-23
-updatedAt: 2025-08-23
+updatedAt: 2025-10-29
 title: Intlayer y next-i18next
-description: Integra Intlayer con next-i18next para una aplicación Next.js
+description: Integra Intlayer con next-i18next para una solución integral de internacionalización en Next.js
 keywords:
   - i18next
   - next-i18next
   - Intlayer
   - Internacionalización
-  - Blogumentación
+  - Blog
   - Next.js
   - JavaScript
   - React
 slugs:
   - blog
   - intlayer-with-next-i18next
+history:
+  - version: 7.0.0
+    date: 2025-10-29
+    changes: Cambio al plugin syncJSON y reescritura integral
 ---
 
-# Next.js Internacionalización (i18n) con next-i18next y Intlayer
+# Internacionalización (i18n) en Next.js con next-i18next e Intlayer
 
-Tanto next-i18next como Intlayer son frameworks de internacionalización (i18n) de código abierto diseñados para aplicaciones de Next.js. Son ampliamente utilizados para gestionar traducciones, localización y cambio de idioma en proyectos de software.
+## Tabla de Contenidos
 
-Ambas soluciones incluyen tres nociones principales:
+<TOC/>
 
-1. **Declaración de Contenido**: El método para definir el contenido traducible de tu aplicación.
-   - Nombrado `resource` en el caso de `i18next`, la declaración de contenido es un objeto JSON estructurado que contiene pares clave-valor para traducciones en uno o varios idiomas. Consulta la [documentación de i18next](https://www.i18next.com/translation-function/essentials) para más información.
-   - Nombrado `archivo de declaración de contenido` en el caso de `Intlayer`, la declaración de contenido puede ser un archivo JSON, JS o TS que exporta los datos estructurados. Consulta la [documentación de Intlayer](https://intlayer.org/fr/doc/concept/content) para más información.
+## ¿Qué es next-i18next?
 
-2. **Utilidades**: Herramientas para construir e interpretar declaraciones de contenido en la aplicación, como `getI18n()`, `useCurrentLocale()`, o `useChangeLocale()` para next-i18next, y `useIntlayer()` o `useLocale()` para Intlayer.
+**next-i18next** es uno de los frameworks de internacionalización (i18n) más populares para aplicaciones Next.js. Construido sobre el poderoso ecosistema de **i18next**, ofrece una solución integral para gestionar traducciones, localización y cambio de idioma en proyectos Next.js.
 
-3. **Plugins y Middleware**: Características para gestionar la redirección de URL, optimización de empaquetado, y más, como `next-i18next/middleware` para next-i18next o `intlayerMiddleware` para Intlayer.
+Sin embargo, next-i18next presenta algunos desafíos:
 
-## Intlayer vs. i18next: Principales Diferencias
+- **Configuración compleja**: Configurar next-i18next requiere múltiples archivos de configuración y una configuración cuidadosa de las instancias i18n del lado del servidor y del cliente.
+- **Traducciones dispersas**: Los archivos de traducción suelen almacenarse en directorios separados de los componentes, lo que dificulta mantener la consistencia.
+- **Gestión manual de namespaces**: Los desarrolladores deben gestionar manualmente los namespaces y asegurar la correcta carga de los recursos de traducción.
+- **Seguridad de tipos limitada**: El soporte para TypeScript requiere configuración adicional y no proporciona generación automática de tipos para las traducciones.
 
-Para explorar las diferencias entre i18next e Intlayer, consulta nuestra publicación de blog [next-i18next vs. next-intl vs. Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/blog/es/i18next_vs_next-intl_vs_intlayer.md).
+## ¿Qué es Intlayer?
 
-## Cómo Generar Diccionarios de next-i18next con Intlayer
+**Intlayer** es una biblioteca innovadora y de código abierto para internacionalización, diseñada para abordar las deficiencias de las soluciones i18n tradicionales. Ofrece un enfoque moderno para la gestión de contenido en aplicaciones Next.js.
 
-### ¿Por qué Usar Intlayer con next-i18next?
+Consulta una comparación concreta con next-intl en nuestro artículo del blog [next-i18next vs. next-intl vs. Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/blog/es/next-i18next_vs_next-intl_vs_intlayer.md).
 
-Los archivos de declaración de contenido de Intlayer generalmente ofrecen una mejor experiencia de desarrollador. Son más flexibles y mantenibles debido a dos ventajas principales:
+## ¿Por qué combinar Intlayer con next-i18next?
 
-1. **Colocación Flexible**: Un archivo de declaración de contenido de Intlayer se puede colocar en cualquier lugar del árbol de archivos de la aplicación, simplificando la gestión de componentes duplicados o eliminados sin dejar declaraciones de contenido no utilizadas.
+Mientras que Intlayer ofrece una excelente solución i18n independiente (consulta nuestra [guía de integración con Next.js](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_with_nextjs_16.md)), es posible que desees combinarlo con next-i18next por varias razones:
 
-   Ejemplos de estructuras de archivos:
+1. **Código existente**: Tienes una implementación establecida de next-i18next y quieres migrar gradualmente a la mejorada experiencia de desarrollo de Intlayer.
+2. **Requisitos heredados**: Tu proyecto requiere compatibilidad con plugins o flujos de trabajo existentes de i18next.
+3. **Familiaridad del equipo**: Tu equipo está cómodo con next-i18next pero desea una mejor gestión de contenido.
 
-   ```bash codeFormat="typescript"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.ts # Archivo de declaración de contenido
-               └── index.tsx
-   ```
+**Para ello, Intlayer puede implementarse como un adaptador para next-i18next que ayude a automatizar tus traducciones JSON en la CLI o en pipelines de CI/CD, probar tus traducciones y más.**
 
-   ```bash codeFormat="esm"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.mjs # Archivo de declaración de contenido
-               └── index.mjx
-   ```
+Esta guía te muestra cómo aprovechar el sistema superior de declaración de contenido de Intlayer mientras mantienes la compatibilidad con next-i18next.
 
-   ```bash codeFormat="cjs"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.cjs # Archivo de declaración de contenido
-               └── index.cjx
-   ```
+---
 
-   ```bash codeFormat="json"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.json # Archivo de declaración de contenido
-               └── index.jsx
-   ```
+## Guía paso a paso para configurar Intlayer con next-i18next
 
-2. **Traducciones Centralizadas**: Intlayer almacena todas las traducciones en un solo archivo, asegurando que no falte ninguna traducción. Al usar TypeScript, las traducciones faltantes se detectan automáticamente y se informan como errores.
+### Paso 1: Instalar dependencias
 
-### Instalación
+Instala los paquetes necesarios usando tu gestor de paquetes preferido:
 
 ```bash packageManager="npm"
-npm install intlayer i18next next-i18next i18next-resources-to-backend
+npm install intlayer @intlayer/sync-json-plugin
 ```
 
-```bash packageManager="yarn"
-yarn add intlayer i18next next-i18next i18next-resources-to-backend
+```bash packageManager="pnpm"
+pnpm add intlayer @intlayer/sync-json-plugin
 ```
 
-```bash packageManager="pnpm"
-pnpm add intlayer i18next next-i18next i18next-resources-to-backend
+```bash packageManager="yarn"
+yarn add intlayer @intlayer/sync-json-plugin
 ```
 
-### Configurando Intlayer para Exportar Diccionarios de i18next
+**Explicación de los paquetes:**
 
-> La exportación de recursos de i18next no asegura una compatibilidad 1:1 con otros frameworks. Se recomienda adherirse a una configuración basada en Intlayer para minimizar problemas.
+- **intlayer**: Biblioteca principal para la declaración y gestión de contenido
+- **next-intlayer**: Capa de integración para Next.js con plugins de compilación
+- **i18next**: Framework principal de i18n
+- **next-i18next**: Wrapper de Next.js para i18next
+- **i18next-resources-to-backend**: Carga dinámica de recursos para i18next
+- **@intlayer/sync-json-plugin**: Plugin para sincronizar las declaraciones de contenido de Intlayer al formato JSON de i18next
 
-Para exportar recursos de i18next, configura Intlayer en un archivo `intlayer.config.ts`. Ejemplos de configuraciones:
+### Paso 2: Implementar el plugin de Intlayer para envolver el JSON
 
-```typescript fileName="intlayer.config.ts" codeFormat="typescript"
-import { Locales, type IntlayerConfig } from "intlayer";
-
-const config: IntlayerConfig = {
-  internationalization: {
-    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
-    defaultLocale: Locales.ENGLISH,
-  },
-  content: {
-    dictionaryOutput: ["i18next"],
-    i18nextResourcesDir: "./i18next/resources",
-  },
-};
+Crea un archivo de configuración de Intlayer para definir los locales soportados:
 
-export default config;
-```
+**Si también quieres exportar diccionarios JSON para i18next**, añade el plugin `syncJSON`:
 
-```javascript fileName="intlayer.config.mjs" codeFormat="esm"
-import { Locales } from "intlayer";
+```typescript fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
 
-/** @type {import('intlayer').IntlayerConfig} */
-const config = {
+const config: IntlayerConfig = {
   internationalization: {
     locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
     defaultLocale: Locales.ENGLISH,
   },
-  content: {
-    dictionaryOutput: ["i18next"],
-    i18nextResourcesDir: "./i18next/resources",
-  },
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./messages/${locale}/${key}.json`,
+    }),
+  ],
 };
 
 export default config;
 ```
 
-```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
-const { Locales } = require("intlayer");
+El plugin `syncJSON` envolverá automáticamente el JSON. Leerá y escribirá los archivos JSON sin cambiar la arquitectura del contenido.
 
-/** @type {import('intlayer').IntlayerConfig} */
-const config = {
-  internationalization: {
-    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
-    defaultLocale: Locales.ENGLISH,
-  },
-  content: {
-    dictionaryOutput: ["i18next"],
-    i18nextResourcesDir: "./i18next/resources",
-  },
-};
+Si deseas hacer coexistir ese JSON con los archivos de declaración de contenido de intlayer (archivos `.content`), Intlayer procederá de la siguiente manera:
 
-module.exports = config;
-```
+    1. cargar tanto los archivos JSON como los archivos de declaración de contenido y transformarlos en un diccionario de intlayer.
+    2. si hay conflictos entre el JSON y los archivos de declaración de contenido, Intlayer procederá a la fusión de todos esos diccionarios. Dependiendo de la prioridad de los plugins y la del archivo de declaración de contenido (todos son configurables).
 
-Aquí está la continuación y corrección de las partes restantes de tu documento:
+Si se realizan cambios usando la CLI para traducir el JSON, o usando el CMS, Intlayer actualizará el archivo JSON con las nuevas traducciones.
 
 ---
 
-### Importando Diccionarios en tu Configuración de i18next
-
-Para importar los recursos generados en tu configuración de i18next, utiliza `i18next-resources-to-backend`. A continuación se muestran ejemplos:
-
-```typescript fileName="i18n/client.ts" codeFormat="typescript"
-import i18next from "i18next";
-import resourcesToBackend from "i18next-resources-to-backend";
-
-i18next.use(
-  resourcesToBackend(
-    (language: string, namespace: string) =>
-      import(`../i18next/resources/${language}/${namespace}.json`)
-  )
-);
-```
-
-```javascript fileName="i18n/client.mjs" codeFormat="esm"
-import i18next from "i18next";
-import resourcesToBackend from "i18next-resources-to-backend";
-
-i18next.use(
-  resourcesToBackend(
-    (language, namespace) =>
-      import(`../i18next/resources/${language}/${namespace}.json`)
-  )
-);
-```
-
-```javascript fileName="i18n/client.cjs" codeFormat="commonjs"
-const i18next = require("i18next");
-const resourcesToBackend = require("i18next-resources-to-backend");
-
-i18next.use(
-  resourcesToBackend(
-    (language, namespace) =>
-      import(`../i18next/resources/${language}/${namespace}.json`)
-  )
-);
-```
-
-### Declaración de Contenido
-
-Ejemplos de archivos de declaración de contenido en varios formatos:
-
-```typescript fileName="**/*.content.ts" contentDeclarationFormat="typescript"
-import { t, type Dictionary } from "intlayer";
-
-const content = {
-  key: "my-content",
-  content: {
-    myTranslatedContent: t({
-      en: "Hello World",
-      es: "Hola Mundo",
-      fr: "Bonjour le monde",
-    }),
-  },
-} satisfies Dictionary;
-
-export default content;
-```
-
-```javascript fileName="**/*.content.mjs" contentDeclarationFormat="esm"
-import { t } from "intlayer";
-
-/** @type {import('intlayer').Dictionary} */
-const content = {
-  key: "my-content",
-  content: {
-    myTranslatedContent: t({
-      en: "Hello World",
-      es: "Hola Mundo",
-      fr: "Bonjour le monde",
-    }),
-  },
-};
-```
-
-```javascript fileName="**/*.content.cjs" contentDeclarationFormat="commonjs"
-const { t } = require("intlayer");
-
-module.exports = {
-  key: "my-content",
-  content: {
-    myTranslatedContent: t({
-      en: "Hello World",
-      es: "Hola Mundo",
-      fr: "Bonjour le monde",
-    }),
-  },
-};
-```
-
-```json fileName="**/*.content.json" contentDeclarationFormat="json"
-{
-  "$schema": "https://intlayer.org/schema.json",
-  "key": "my-content",
-  "content": {
-    "myTranslatedContent": {
-      "nodeType": "translation",
-      "translation": {
-        "en": "Hello World",
-        "fr": "Bonjour le monde",
-        "es": "Hola Mundo"
-      }
-    }
-  }
-}
-```
-
-### Construye los Recursos de next-i18next
-
-Para construir los recursos de next-i18next, ejecuta el siguiente comando:
-
-```bash packageManager="npm"
-npx run intlayer build
-```
-
-```bash packageManager="yarn"
-yarn intlayer build
-```
+## Configuración de Git
 
-```bash packageManager="pnpm"
-pnpm intlayer build
-```
-
-Esto generará recursos en el directorio `./i18next/resources`. La salida esperada:
-
-```bash
-.
-└── i18next
-    └── resources
-       └── en
-           └── my-content.json
-       └── fr
-           └── my-content.json
-       └── es
-           └── my-content.json
-```
-
-Nota: El espacio de nombres de i18next corresponde a la clave de declaración de Intlayer.
-
-### Implementar el Plugin de Next.js
-
-Una vez configurado, implementa el plugin de Next.js para reconstruir tus recursos de i18next cada vez que los archivos de declaración de contenido de Intlayer se actualicen.
-
-```typescript fileName="next.config.mjs"
-import { withIntlayer } from "next-intlayer/server";
-
-/** @type {import('next').NextConfig} */
-const nextConfig = {};
-
-export default withIntlayer(nextConfig);
-```
+Excluir archivos generados del control de versiones:
 
-### Usando Contenido en Componentes de Next.js
-
-Después de implementar el plugin de Next.js, puedes usar el contenido en tus componentes:
-
-```typescript fileName="src/components/myComponent/index.tsx" codeFormat="typescript"
-import type { FC } from "react";
-import { useTranslation } from "react-i18next";
-
-const IndexPage: FC = () => {
-  const { t } = useTranslation();
-
-  return (
-    <div>
-      <h1>{t("my-content.title")}</h1>
-      <p>{t("my-content.description")}</p>
-    </div>
-  );
-};
-
-export default IndexPage;
+```plaintext fileName=".gitignore"
+# Ignorar archivos generados por Intlayer
+.intlayer
+intl
 ```
 
-```jsx fileName="src/components/myComponent/index.mjx" codeFormat="esm"
-import { useTranslation } from "react-i18next";
+Estos archivos se regeneran automáticamente durante el proceso de compilación y no necesitan ser comprometidos en tu repositorio.
 
-const IndexPage = () => {
-  const { t } = useTranslation();
+### Extensión de VS Code
 
-  return (
-    <div>
-      <h1>{t("my-content.title")}</h1>
-      <p>{t("my-content.description")}</p>
-    </div>
-  );
-};
-```
-
-```jsx fileName="src/components/myComponent/index.cjx" codeFormat="commonjs"
-const { useTranslation } = require("react-i18next");
+Para mejorar la experiencia del desarrollador, instala la **Extensión oficial de Intlayer para VS Code**:
 
-const IndexPage = () => {
-  const { t } = useTranslation();
+[Instalar desde el Marketplace de VS Code](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
 
-  return (
-    <div>
-      <h1>{t("my-content.title")}</h1>
-      <p>{t("my-content.description")}</p>
-    </div>
-  );
-};
-```
+[Instalar desde el Marketplace de VS Code](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)