@intlayer/docs 5.5.10 → 5.5.12

package/blog/es/intlayer_with_react-i18next.md

@@ -0,0 +1,346 @@
+---
+createdAt: 2025-01-02
+updatedAt: 2025-06-29
+title: Intlayer y react-i18next
+description: Comparar Intlayer con react-i18next para una aplicación React
+keywords:
+  - react-i18next
+  - i18next
+  - Intlayer
+  - Internacionalización
+  - Blogumentación
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - blog
+  - intlayer-with-react-i18next
+---
+
+# 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
+```
+
+### ¿Qué Son Estos Paquetes?
+
+- **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.
+
+## 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"],
+
+    // Elige un directorio de salida para los recursos generados
+    // Esta carpeta se creará si no existe.
+    i18nextResourcesDir: "./i18next/resources",
+  },
+};
+
+export default config;
+```
+
+> **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).
+
+## Construyendo los Recursos de i18next
+
+Una vez que tus declaraciones de contenido estén en su lugar (sección siguiente), ejecuta el **comando de construcción de Intlayer**:
+
+```bash
+# Con npm
+npx run intlayer build
+```
+
+```bash
+# Con yarn
+yarn intlayer build
+```
+
+```bash
+# Con pnpm
+pnpm intlayer build
+```
+
+> Esto generará tus recursos de i18next dentro del directorio `./i18next/resources` por defecto.
+
+Una salida típica podría verse así:
+
+```bash
+.
+└── i18next
+    └── resources
+       ├── en
+       │   └── my-content.json
+       ├── fr
+       │   └── my-content.json
+       └── es
+           └── my-content.json
+```
+
+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;
+```
+
+```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;
+```
+
+Luego, en tu archivo **raíz** o **índice** (por ejemplo, `src/index.tsx`), importa esta configuración de `i18n` **antes** de renderizar la `App`:
+
+```typescript
+import React from "react";
+import ReactDOM from "react-dom/client";
+// Inicializa i18n antes de cualquier otra cosa
+import "./i18n";
+import App from "./App";
+
+ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);
+```
+
+## Creando y Gestionando Tus Declaraciones de Contenido
+
+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:
+
+```typescript title="src/components/MyComponent/MyComponent.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+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",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+    }),
+    description: t({
+      en: "My i18n description text...",
+      fr: "Ma description en i18n...",
+      es: "Mi descripción en i18n...",
+    }),
+  },
+} 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>
+  );
+};
+
+export default MyComponent;
+```
+
+> 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")`.
+
+## Opcional: Integrarse con Scripts de Create React App (CRACO)
+
+**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. **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`:
+
+   ```jsonc
+   "scripts": {
+     "start": "react-intlayer start",
+     "build": "react-intlayer build",
+     "transpile": "intlayer build"
+   }
+   ```
+
+   > 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
+
+**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`:
+
+```json5 title="tsconfig.json"
+{
+  "compilerOptions": {
+    // ...
+  },
+  "include": ["src", "types"],
+}
+```
+
+> Esto permitirá que TypeScript infiera la estructura de tus traducciones para una mejor autocompletación y detección de errores.
+
+## Configuración de Git
+
+Se recomienda **ignorar** archivos y carpetas generados automáticamente por Intlayer. Agrega esta línea a tu `.gitignore`:
+
+```plaintext
+# Ignorar los archivos generados por Intlayer
+.intlayer
+i18next
+```
+
+Por lo general, no debes **comprometer** estos recursos o artefactos internos de construcción `.intlayer`, ya que pueden regenerarse en cada construcción.

package/blog/es/intlayer_with_react-intl.md

@@ -0,0 +1,325 @@
+---
+createdAt: 2025-01-02
+updatedAt: 2025-06-29
+title: Intlayer y react-intl
+description: Integra Intlayer con react-intl para una aplicación React
+keywords:
+  - react-intl
+  - Intlayer
+  - Internacionalización
+  - Blogumentación
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - blog
+  - intlayer-with-react-intl
+---
+
+# React Internationalization (i18n) with **react-intl** y Intlayer
+
+Esta guía muestra cómo integrar **Intlayer** con **react-intl** para gestionar traducciones en una aplicación React. Declararás tu contenido traducible con Intlayer y luego consumirás esos mensajes con **react-intl**, una biblioteca popular del ecosistema [FormatJS](https://formatjs.io/docs/react-intl).
+
+## Visión General
+
+- **Intlayer** te permite almacenar traducciones en archivos de declaración de contenido a **nivel de componente** (JSON, JS, TS, etc.) dentro de tu proyecto.
+- **react-intl** proporciona componentes y hooks de React (como `<FormattedMessage>` y `useIntl()`) para mostrar cadenas localizadas.
+
+Al configurar Intlayer para **exportar** traducciones en un formato **compatible con react-intl**, puedes **generar** y **actualizar** automáticamente los archivos de mensajes que requiere `<IntlProvider>` (de react-intl).
+
+---
+
+## ¿Por qué usar Intlayer con react-intl?
+
+1. **Declaraciones de Contenido por Componente**  
+   Los archivos de declaración de contenido de Intlayer pueden vivir junto a tus componentes de React, evitando traducciones “huérfanas” si los componentes se mueven o se eliminan. Por ejemplo:
+
+   ```bash
+   .
+   └── src
+       └── components
+           └── MyComponent
+               ├── index.content.ts   # Declaración de contenido de Intlayer
+               └── index.tsx          # Componente React
+   ```
+
+2. **Traducciones Centralizadas**  
+   Cada archivo de declaración de contenido recopila todas las traducciones necesarias para un componente. Esto es particularmente útil en proyectos de TypeScript: las traducciones faltantes se pueden detectar en **tiempo de compilación**.
+
+3. **Generación Automática y Regeneración**  
+   Siempre que agregues o actualices traducciones, Intlayer regenerará los archivos JSON de mensajes. Luego puedes pasarlos al `<IntlProvider>` de react-intl.
+
+---
+
+## Instalación
+
+En un proyecto típico de React, instala lo siguiente:
+
+```bash
+# con npm
+npm install intlayer react-intl
+
+# con yarn
+yarn add intlayer react-intl
+
+# con pnpm
+pnpm add intlayer react-intl
+```
+
+### ¿Por qué estos paquetes?
+
+- **intlayer**: CLI y biblioteca principal que escanea las declaraciones de contenido, las fusiona y construye salidas de diccionario.
+- **react-intl**: La biblioteca principal de FormatJS que proporciona `<IntlProvider>`, `<FormattedMessage>`, `useIntl()` y otros elementos básicos de internacionalización.
+
+> Si aún no tienes React instalado, también lo necesitarás (`react` y `react-dom`).
+
+## Configurando Intlayer para Exportar Mensajes react-intl
+
+En la raíz de tu proyecto, crea **`intlayer.config.ts`** (o `.js`, `.mjs`, `.cjs`) de la siguiente manera:
+
+```typescript title="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    // Agrega tantas locales como desees
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  content: {
+    // Indica a Intlayer que genere archivos de mensajes para react-intl
+    dictionaryOutput: ["react-intl"],
+
+    // El directorio donde Intlayer escribirá tus archivos JSON de mensajes
+    reactIntlMessagesDir: "./react-intl/messages",
+  },
+};
+
+export default config;
+```
+
+> **Nota**: Para otras extensiones de archivo (`.mjs`, `.cjs`, `.js`), consulta la [documentación de Intlayer](https://intlayer.org/es/doc/concept/configuration) para detalles de uso.
+
+---
+
+## Creando Tus Declaraciones de Contenido de Intlayer
+
+Intlayer escanea tu base de código (por defecto, bajo `./src`) en busca de archivos que coincidan con `*.content.{ts,tsx,js,jsx,mjs,mjx,cjs,cjx,json}`.  
+Aquí hay un ejemplo de **TypeScript**:
+
+```typescript title="src/components/MyComponent/index.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+const content = {
+  // "key" se convierte en la clave de mensaje de nivel superior en tu archivo JSON de react-intl
+  key: "my-component",
+
+  content: {
+    // Cada llamada a t() declara un campo traducible
+    helloWorld: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+    }),
+    description: t({
+      en: "This is a description",
+      fr: "Ceci est une description",
+      es: "Esta es una descripción",
+    }),
+  },
+} satisfies Dictionary;
+
+export default content;
+```
+
+Si prefieres JSON o diferentes sabores de JS (`.cjs`, `.mjs`), la estructura es en gran medida la misma, consulta [documentación de Intlayer sobre declaración de contenido](https://intlayer.org/es/doc/concept/content).
+
+---
+
+## Construyendo los Mensajes de react-intl
+
+Para generar los archivos JSON de mensajes reales para **react-intl**, ejecuta:
+
+```bash
+# con npm
+npx intlayer dictionaries build
+
+# con yarn
+yarn intlayer build
+
+# con pnpm
+pnpm intlayer build
+```
+
+Esto escanea todos los archivos `*.content.*`, los compila y escribe los resultados en el directorio especificado en tu **`intlayer.config.ts`** , en este ejemplo, `./react-intl/messages`.  
+Una salida típica podría verse así:
+
+```bash
+.
+└── react-intl
+    └── messages
+        ├── en.json
+        ├── fr.json
+        └── es.json
+```
+
+Cada archivo es un objeto JSON cuyas **claves de nivel superior** corresponden a cada **`content.key`** de tus declaraciones. Las **sub-claves** (como `helloWorld`) reflejan las traducciones declaradas dentro de ese ítem de contenido.
+
+Por ejemplo, el **en.json** podría verse así:
+
+```json fileName="react-intl/messages/en/my-component.json"
+{
+  "helloWorld": "Hello World",
+  "description": "This is a description"
+}
+```
+
+---
+
+## Inicializando react-intl en Tu Aplicación React
+
+### 1. Cargar los Mensajes Generados
+
+Donde configuras el componente raíz de tu aplicación (por ejemplo, `src/main.tsx` o `src/index.tsx`), deberás:
+
+1. **Importar** los archivos de mensajes generados (ya sea de forma estática o dinámica).
+2. **Proveer** estos a `<IntlProvider>` de `react-intl`.
+
+Un enfoque simple es importarlos **estáticamente**:
+
+```typescript title="src/index.tsx"
+import React from "react";
+import ReactDOM from "react-dom/client";
+import { IntlProvider } from "react-intl";
+import App from "./App";
+
+// Importa los archivos JSON de la salida de construcción.
+// Alternativamente, puedes importar dinámicamente según la elección de idioma del usuario.
+import en from "../react-intl/messages/en.json";
+import fr from "../react-intl/messages/fr.json";
+import es from "../react-intl/messages/es.json";
+
+// Si tienes un mecanismo para detectar el idioma del usuario, configúralo aquí.
+// Para simplicidad, elijamos inglés.
+const locale = "en";
+
+// Reúne los mensajes en un objeto (o escógelos dinámicamente)
+const messagesRecord: Record<string, Record<string, any>> = {
+  en,
+  fr,
+  es,
+};
+
+ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
+  <React.StrictMode>
+    <IntlProvider locale={locale} messages={messagesRecord[locale]}>
+      <App />
+    </IntlProvider>
+  </React.StrictMode>
+);
+```
+
+> **Consejo**: Para proyectos reales, podrías:
+>
+> - Cargar dinámicamente los mensajes JSON en tiempo de ejecución.
+> - Usar detección de local basado en el entorno, navegador o cuenta de usuario.
+
+### 2. Usar `<FormattedMessage>` o `useIntl()`
+
+Una vez que tus mensajes están cargados en `<IntlProvider>`, cualquier componente hijo puede usar react-intl para acceder a cadenas localizadas. Hay dos enfoques principales:
+
+- **Componente `<FormattedMessage>`**
+- **Hook `useIntl()`**
+
+---
+
+## Usando Traducciones en Componentes React
+
+### Enfoque A: `<FormattedMessage>`
+
+Para un uso rápido en línea:
+
+```tsx title="src/components/MyComponent/index.tsx"
+import React from "react";
+import { FormattedMessage } from "react-intl";
+
+export default function MyComponent() {
+  return (
+    <div>
+      <h1>
+        {/* “my-component.helloWorld” se refiere a la clave de en.json, fr.json, etc. */}
+        <FormattedMessage id="my-component.helloWorld" />
+      </h1>
+
+      <p>
+        <FormattedMessage id="my-component.description" />
+      </p>
+    </div>
+  );
+}
+```
+
+> La prop **`id`** en `<FormattedMessage>` debe coincidir con la **clave de nivel superior** (`my-component`) más cualquier sub-clave (`helloWorld`).
+
+### Enfoque B: `useIntl()`
+
+Para un uso más dinámico:
+
+```tsx title="src/components/MyComponent/index.tsx"
+import React from "react";
+import { useIntl } from "react-intl";
+
+export default function MyComponent() {
+  const intl = useIntl();
+
+  return (
+    <div>
+      <h1>{intl.formatMessage({ id: "my-component.helloWorld" })}</h1>
+      <p>{intl.formatMessage({ id: "my-component.description" })}</p>
+    </div>
+  );
+}
+```
+
+Cualquiera de los enfoques es válido: elige el estilo que mejor se adapte a tu aplicación.
+
+---
+
+## Actualizando o Agregando Nuevas Traducciones
+
+1. **Agrega o modifica** contenido en cualquier archivo `*.content.*`.
+2. Vuelve a ejecutar `intlayer build` para regenerar los archivos JSON en `./react-intl/messages`.
+3. React (y react-intl) detectarán las actualizaciones la próxima vez que reconstruyas o recargues tu aplicación.
+
+---
+
+## Integración con TypeScript (Opcional)
+
+Si estás usando TypeScript, Intlayer puede **generar definiciones de tipo** para tus traducciones.
+
+- Asegúrate de que `tsconfig.json` incluya tu carpeta `types` (o cualquier carpeta de salida que genere Intlayer) en el arreglo `"include"`.
+
+```json5
+{
+  "compilerOptions": {
+    // ...
+  },
+  "include": ["src", "types"],
+}
+```
+
+Los tipos generados pueden ayudar a detectar traducciones faltantes o claves inválidas en tus componentes de React en tiempo de compilación.
+
+---
+
+## Configuración de Git
+
+Es común **excluir** los artefactos de construcción internos de Intlayer del control de versiones. En tu `.gitignore`, añade:
+
+```plaintext
+# Ignorar artefactos de construcción de intlayer
+.intlayer
+react-intl
+```
+
+Dependiendo de tu flujo de trabajo, también puede que desees ignorar o confirmar los diccionarios finales en `./react-intl/messages`. Si tu canal de CI/CD los regenera, puedes ignorarlos de forma segura; de lo contrario, confírmales si los necesitas para las implementaciones de producción.