@intlayer/docs 7.0.3 → 7.0.4

package/blog/es/intlayer_with_react-i18next.md

@@ -1,346 +1,124 @@
 ---
 createdAt: 2025-01-02
-updatedAt: 2025-06-29
-title: Intlayer y react-i18next
-description: Comparar Intlayer con react-i18next para una aplicación React
+updatedAt: 2025-10-29
+title: Cómo automatizar tus traducciones JSON de react-i18next usando Intlayer
+description: Automatiza tus traducciones JSON con Intlayer y react-i18next para una internacionalización mejorada en aplicaciones React.
 keywords:
   - react-i18next
   - i18next
   - Intlayer
   - Internacionalización
-  - Blogumentación
-  - Next.js
-  - JavaScript
+  - i18n
+  - Blog
   - React
+  - JavaScript
+  - TypeScript
+  - Gestión de Contenido
 slugs:
   - blog
   - intlayer-with-react-i18next
+history:
+  - version: 7.0.0
+    date: 2025-10-29
+    changes: Cambio al plugin syncJSON
 ---
 
-# React Internationalization (i18n) con react-i18next y Intlayer
-
-## Resumen
-
-- **Intlayer** te ayuda a gestionar traducciones a través de archivos de declaración de contenido a **nivel de componente**.
-- **react-i18next** es una integración popular de React para **i18next** que proporciona hooks como `useTranslation` para obtener cadenas localizadas en tus componentes.
-
-Cuando se combinan, Intlayer puede **exportar** diccionarios en **JSON compatible con i18next**, de modo que react-i18next pueda **consumirlos** en tiempo de ejecución.
-
-## ¿Por Qué Usar Intlayer con react-i18next?
-
-Los archivos de declaración de contenido **Intlayer** ofrecen una mejor experiencia para desarrolladores porque son:
-
-1. **Flexibles en la Ubicación de Archivos**  
-   Coloca cada archivo de declaración de contenido justo al lado del componente que lo necesita. Esta estructura te permite mantener las traducciones co-localizadas, evitando traducciones huérfanas cuando los componentes se mueven o se eliminan.
-
-   ```bash codeFormat="typescript"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.ts # Archivo de declaración de contenido
-               └── index.tsx
-   ```
-
-   ```bash codeFormat="esm"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.mjs # Archivo de declaración de contenido
-               └── index.mjx
-   ```
-
-   ```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
-   ```
-
-2. **Traducciones Centralizadas**  
-   Un solo archivo de declaración de contenido recopila todas las traducciones necesarias para un componente, haciendo que las traducciones faltantes sean más fáciles de detectar.  
-   Con TypeScript, incluso obtienes errores en tiempo de compilación si faltan traducciones.
-
-## Instalación
-
-En un proyecto de Create React App, instala estas dependencias:
-
-```bash
-# Con npm
-npm install intlayer react-i18next i18next i18next-resources-to-backend
-```
-
-```bash
-# Con yarn
-yarn add intlayer react-i18next i18next i18next-resources-to-backend
-```
-
-```bash
-# Con pnpm
-pnpm add intlayer react-i18next i18next i18next-resources-to-backend
-```
+# Cómo automatizar tus traducciones JSON de react-i18next usando Intlayer
 
-### ¿Qué Son Estos Paquetes?
+## ¿Qué es Intlayer?
 
-- **intlayer** – La CLI y biblioteca central para gestionar configuraciones de i18n, declaraciones de contenido y construir salidas de diccionario.
-- **react-intlayer** – Integración específica de React para Intlayer, proporcionando notablemente algunos scripts para automatizar la construcción de diccionarios.
-- **react-i18next** – Biblioteca de integración específica de React para i18next, incluyendo el hook `useTranslation`.
-- **i18next** – El marco subyacente para el manejo de traducciones.
-- **i18next-resources-to-backend** – Un backend de i18next que importa dinámicamente recursos JSON.
+**Intlayer** es una biblioteca innovadora y de código abierto para la internacionalización, diseñada para abordar las limitaciones de las soluciones i18n tradicionales. Ofrece un enfoque moderno para la gestión de contenido en aplicaciones React.
 
-## Configurando Intlayer para Exportar Diccionarios de i18next
-
-Crea (o actualiza) tu `intlayer.config.ts` en la raíz de tu proyecto:
-
-```typescript title="intlayer.config.ts"
-import { Locales, type IntlayerConfig } from "intlayer";
-
-const config: IntlayerConfig = {
-  internationalization: {
-    // Agrega tantos locales como desees
-    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
-    defaultLocale: Locales.ENGLISH,
-  },
-  content: {
-    // Indica a Intlayer que cree JSON compatible con i18next
-    dictionaryOutput: ["i18next"],
+Consulta una comparación concreta con react-i18next en nuestro artículo del blog [react-i18next vs. react-intl vs. Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/blog/es/react-i18next_vs_react-intl_vs_intlayer.md).
 
-    // Elige un directorio de salida para los recursos generados
-    // Esta carpeta se creará si no existe.
-    i18nextResourcesDir: "./i18next/resources",
-  },
-};
+## ¿Por qué combinar Intlayer con react-i18next?
 
-export default config;
-```
+Aunque Intlayer proporciona una excelente solución i18n independiente (consulta nuestra [guía de integración con React](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/intlayer_with_vite+react.md)), es posible que desees combinarlo con react-i18next por varias razones:
 
-> **Nota**: Si no estás usando TypeScript, puedes crear este archivo de configuración como `.cjs`, `.mjs` o `.js` (consulta la [documentación de Intlayer](https://intlayer.org/en/doc/concept/configuration) para más detalles).
+1. **Base de código existente**: Tienes una implementación establecida de react-i18next y quieres migrar gradualmente a la mejor experiencia de desarrollo que ofrece Intlayer.
+2. **Requisitos heredados**: Tu proyecto requiere compatibilidad con plugins o flujos de trabajo existentes de react-i18next.
+3. **Familiaridad del equipo**: Tu equipo está cómodo con react-i18next pero desea una mejor gestión del contenido.
 
-## Construyendo los Recursos de i18next
+**Para ello, Intlayer puede implementarse como un adaptador para react-i18next que ayude a automatizar tus traducciones JSON en la línea de comandos o en pipelines CI/CD, probar tus traducciones y más.**
 
-Una vez que tus declaraciones de contenido estén en su lugar (sección siguiente), ejecuta el **comando de construcción de Intlayer**:
+Esta guía te muestra cómo aprovechar el sistema superior de declaración de contenido de Intlayer mientras mantienes la compatibilidad con react-i18next.
 
-```bash
-# Con npm
-npx run intlayer build
-```
+## Tabla de Contenidos
 
-```bash
-# Con yarn
-yarn intlayer build
-```
+<TOC/>
 
-```bash
-# Con pnpm
-pnpm intlayer build
-```
+## Guía paso a paso para configurar Intlayer con react-i18next
 
-> Esto generará tus recursos de i18next dentro del directorio `./i18next/resources` por defecto.
+### Paso 1: Instalar dependencias
 
-Una salida típica podría verse así:
+Instala los paquetes necesarios:
 
-```bash
-.
-└── i18next
-    └── resources
-       ├── en
-       │   └── my-content.json
-       ├── fr
-       │   └── my-content.json
-       └── es
-           └── my-content.json
+```bash packageManager="npm"
+npm install intlayer @intlayer/sync-json-plugin
 ```
 
-Donde cada clave de declaración de **Intlayer** se utiliza como un **espacio de nombres de i18next** (por ejemplo, `my-content.json`).
-
-## Importando Diccionarios en tu Configuración de react-i18next
-
-Para cargar dinámicamente estos recursos en tiempo de ejecución, utiliza [`i18next-resources-to-backend`](https://www.npmjs.com/package/i18next-resources-to-backend). Por ejemplo, crea un archivo `i18n.ts` (o `.js`) en tu proyecto:
-
-```typescript title="i18n.ts"
-import i18next from "i18next";
-import { initReactI18next } from "react-i18next";
-import resourcesToBackend from "i18next-resources-to-backend";
-
-i18next
-  // plugin react-i18next
-  .use(initReactI18next)
-  // carga dinámicamente los recursos
-  .use(
-    resourcesToBackend((language: string, namespace: string) => {
-      // Ajusta la ruta de importación a tu directorio de recursos
-      return import(`../i18next/resources/${language}/${namespace}.json`);
-    })
-  )
-  // Inicializa i18next
-  .init({
-    // Localidad de respaldo
-    fallbackLng: "en",
-
-    // Puedes agregar otras opciones de configuración de i18next aquí, consulta:
-    // https://www.i18next.com/overview/configuration-options
-  });
-
-export default i18next;
+```bash packageManager="pnpm"
+pnpm add intlayer @intlayer/sync-json-plugin
 ```
 
-```javascript title="i18n.js"
-import i18next from "i18next";
-import { initReactI18next } from "react-i18next";
-import resourcesToBackend from "i18next-resources-to-backend";
-
-i18next
-  .use(initReactI18next)
-  .use(
-    resourcesToBackend(
-      (language, namespace) =>
-        import(`../i18next/resources/${language}/${namespace}.json`)
-    )
-  )
-  .init({
-    fallbackLng: "en",
-  });
-
-export default i18next;
+```bash packageManager="yarn"
+yarn add intlayer @intlayer/sync-json-plugin
 ```
 
-Luego, en tu archivo **raíz** o **índice** (por ejemplo, `src/index.tsx`), importa esta configuración de `i18n` **antes** de renderizar la `App`:
+**Descripción de los paquetes:**
 
-```typescript
-import React from "react";
-import ReactDOM from "react-dom/client";
-// Inicializa i18n antes de cualquier otra cosa
-import "./i18n";
-import App from "./App";
+- **intlayer**: Biblioteca principal para la gestión de internacionalización, declaración de contenido y construcción
+- **@intlayer/sync-json-plugin**: Plugin para exportar declaraciones de contenido de Intlayer a un formato JSON compatible con react-i18next
 
-ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
-  <React.StrictMode>
-    <App />
-  </React.StrictMode>
-);
-```
+### Paso 2: Implementar el plugin de Intlayer para envolver el JSON
 
-## Creando y Gestionando Tus Declaraciones de Contenido
+Crea un archivo de configuración de Intlayer para definir los locales que soportas:
 
-Intlayer extrae traducciones de "archivos de declaración de contenido" ubicados en cualquier lugar debajo de `./src` (por defecto).  
-Aquí hay un ejemplo mínimo en TypeScript:
+**Si también quieres exportar diccionarios JSON para react-i18next**, añade el plugin `syncJSON`:
 
-```typescript title="src/components/MyComponent/MyComponent.content.ts"
-import { t, type Dictionary } from "intlayer";
+```typescript fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
 
-const content = {
-  // La "clave" será tu espacio de nombres de i18next (por ejemplo, "my-component")
-  key: "my-component",
-  content: {
-    // Cada llamada "t" es un nodo de traducción separado
-    heading: t({
-      en: "Hello World",
-      es: "Hola Mundo",
-      fr: "Bonjour le monde",
-    }),
-    description: t({
-      en: "My i18n description text...",
-      fr: "Ma description en i18n...",
-      es: "Mi descripción en i18n...",
-    }),
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
   },
-} satisfies Dictionary;
-
-export default content;
-```
-
-Si prefieres JSON, `.cjs` o `.mjs`, consulta la [documentación de Intlayer](https://intlayer.org/en/doc/concept/content).
-
-> Por defecto, las declaraciones de contenido válidas coinciden con el patrón de extensión de archivo:
-
-> `*.content.{ts,tsx,js,jsx,mjs,mjx,cjs,cjx,json}`
-
-## Usando las Traducciones en Componentes de React
-
-Después de que hayas **construido** tus recursos de Intlayer y configurado react-i18next, puedes usar directamente el hook `useTranslation` de **react-i18next**.  
-Por ejemplo:
-
-```tsx title="src/components/MyComponent/MyComponent.tsx"
-import type { FC } from "react";
-import { useTranslation } from "react-i18next";
-
-/**
- * El "espacio de nombres" de i18next es la `clave` de Intlayer de "MyComponent.content.ts"
- * así que pasaremos "my-component" a useTranslation().
- */
-const MyComponent: FC = () => {
-  const { t } = useTranslation("my-component");
-
-  return (
-    <div>
-      <h1>{t("heading")}</h1>
-      <p>{t("description")}</p>
-    </div>
-  );
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./messages/${locale}/${key}.json`,
+    }),
+  ],
 };
 
-export default MyComponent;
+export default config;
 ```
 
-> Ten en cuenta que la función `t` hace referencia a **claves** dentro de tu JSON generado. Para una entrada de contenido de Intlayer llamada `heading`, usarás `t("heading")`.
+El plugin `syncJSON` envolverá automáticamente el JSON. Leerá y escribirá los archivos JSON sin cambiar la arquitectura del contenido.
 
-## Opcional: Integrarse con Scripts de Create React App (CRACO)
+Si deseas hacer coexistir ese JSON con los archivos de declaración de contenido de intlayer (`.content`), Intlayer procederá de la siguiente manera:
 
-**react-intlayer** proporciona un enfoque basado en CRACO para construcciones personalizadas y configuración del servidor de desarrollo. Si deseas que el paso de construcción de Intlayer se integre sin problemas, puedes:
+    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 fusionar todos esos diccionarios. Dependiendo de la prioridad de los plugins y la del archivo de declaración de contenido (todos son configurables).
 
-1. **Instalar react-intlayer** (si no lo has hecho):
-   ```bash
-   npm install react-intlayer --save-dev
-   ```
-2. **Ajustar tus scripts de `package.json`** para usar los scripts de `react-intlayer`:
+Si se realizan cambios usando la CLI para traducir el JSON, o usando el CMS, Intlayer actualizará el archivo JSON con las nuevas traducciones.
 
-   ```jsonc
-   "scripts": {
-     "start": "react-intlayer start",
-     "build": "react-intlayer build",
-     "transpile": "intlayer build"
-   }
-   ```
+Para ver más detalles sobre el plugin `syncJSON`, por favor consulte la [documentación del plugin syncJSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/es/plugins/sync-json.md).
 
-   > Los scripts de `react-intlayer` se basan en [CRACO](https://craco.js.org/). También puedes implementar tu propia configuración basada en el plugin craco de intlayer. [Consulta un ejemplo aquí](https://github.com/aymericzip/intlayer/blob/main/examples/react-app/craco.config.js).
-
-Ahora, al ejecutar `npm run build`, `yarn build`, o `pnpm build` se activan las construcciones de Intlayer y CRA.
-
-## Configuración de TypeScript
+## Configuración de Git
 
-**Intlayer** proporciona **definiciones de tipo autogeneradas** para tu contenido. Para asegurarte de que TypeScript las reconozca, agrega **`types`** (o `types` si lo configuraste de otro modo) a tu arreglo **include** de `tsconfig.json`:
+Se recomienda ignorar los archivos generados automáticamente por Intlayer:
 
-```json5 title="tsconfig.json"
-{
-  "compilerOptions": {
-    // ...
-  },
-  "include": ["src", "types"],
-}
+```plaintext fileName=".gitignore"
+# Ignorar archivos generados por Intlayer
+.intlayer
 ```
 
-> Esto permitirá que TypeScript infiera la estructura de tus traducciones para una mejor autocompletación y detección de errores.
-
-## Configuración de Git
+Estos archivos pueden ser regenerados durante su proceso de compilación y no necesitan ser comprometidos en el control de versiones.
 
-Se recomienda **ignorar** archivos y carpetas generados automáticamente por Intlayer. Agrega esta línea a tu `.gitignore`:
+### Extensión de VS Code
 
-```plaintext
-# Ignorar los archivos generados por Intlayer
-.intlayer
-i18next
-```
+Para mejorar la experiencia del desarrollador, instale la extensión oficial **Intlayer VS Code Extension**:
 
-Por lo general, no debes **comprometer** estos recursos o artefactos internos de construcción `.intlayer`, ya que pueden regenerarse en cada construcción.
+[Instalar desde el Marketplace de VS Code](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)