@intlayer/docs 5.5.8

package/es/packages/react-intlayer/index.md

@@ -0,0 +1,263 @@
+# react-intlayer: Paquete NPM para internacionalizar (i18n) una aplicación React
+
+**Intlayer** es un conjunto de paquetes diseñados específicamente para desarrolladores de JavaScript. Es compatible con frameworks como React, React y Express.js.
+
+**El paquete `react-intlayer`** te permite internacionalizar tu aplicación React. Proporciona proveedores de contexto y hooks para la internacionalización en React.
+
+## ¿Por qué internacionalizar tu aplicación React?
+
+Internacionalizar tu aplicación React es esencial para atender eficazmente a una audiencia global. Permite que tu aplicación entregue contenido y mensajes en el idioma preferido de cada usuario. Esta capacidad mejora la experiencia del usuario y amplía el alcance de tu aplicación al hacerla más accesible y relevante para personas de diferentes antecedentes lingüísticos.
+
+## ¿Por qué integrar Intlayer?
+
+- **Gestión de contenido impulsada por JavaScript**: Aprovecha la flexibilidad de JavaScript para definir y gestionar tu contenido de manera eficiente.
+- **Entorno seguro para tipos**: Utiliza TypeScript para garantizar que todas tus definiciones de contenido sean precisas y sin errores.
+- **Archivos de contenido integrados**: Mantén tus traducciones cerca de sus respectivos componentes, mejorando la mantenibilidad y claridad.
+
+## Instalación
+
+Instala el paquete necesario utilizando tu gestor de paquetes preferido:
+
+```bash packageManager="npm"
+npm install react-intlayer
+```
+
+```bash packageManager="yarn"
+yarn add react-intlayer
+```
+
+```bash packageManager="pnpm"
+pnpm add react-intlayer
+```
+
+## Ejemplo de uso
+
+Con Intlayer, puedes declarar tu contenido de manera estructurada en cualquier lugar de tu base de código.
+
+Por defecto, Intlayer busca archivos con la extensión `.content.{json,ts,tsx,js,jsx,mjs,mjx,cjs,cjx}`.
+
+> Puedes modificar la extensión predeterminada configurando la propiedad `contentDir` en el [archivo de configuración](https://github.com/aymericzip/intlayer/blob/main/docs/es/configuration.md).
+
+```bash codeFormat="typescript"
+.
+├── intlayer.config.ts
+└── src
+    └── components
+        ├── Component1
+        │   ├── index.content.ts
+        │   └── index.tsx
+        └── Component2
+            ├── index.content.ts
+            └── index.tsx
+```
+
+```bash codeFormat="esm"
+.
+├── intlayer.config.mjs
+└── src
+    └── components
+        ├── Component1
+        │   ├── index.content.mjs
+        │   └── index.mjx
+        └── Component2
+            ├── index.content.mjs
+            └── index.mjx
+```
+
+```bash codeFormat="commonjs"
+.
+├── intlayer.config.cjs
+└── src
+    └── components
+        ├── Component1
+        │   ├── index.content.cjs
+        │   └── index.cjx
+        └── Component2
+            ├── index.content.cjs
+            └── index.cjx
+```
+
+### Declara tu contenido
+
+`react-intlayer` está diseñado para trabajar con el paquete [`intlayer`](https://github.com/aymericzip/intlayer/blob/main/docs/es/packages/intlayer/index.md). `intlayer` es un paquete que te permite declarar tu contenido en cualquier lugar de tu código. Convierte las declaraciones de contenido multilingüe en diccionarios estructurados que se integran perfectamente en tu aplicación.
+
+Aquí tienes un ejemplo de declaración de contenido:
+
+```tsx fileName="src/Component1/index.content.ts" codeFormat="typescript"
+// Declaración de contenido para el componente 1
+import { t, type Dictionary } from "intlayer";
+
+const component1Content = {
+  key: "component-1",
+  content: {
+    myTranslatedContent: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+    }),
+    numberOfCar: enu({
+      "<-1": "Menos de menos un coche",
+      "-1": "Menos un coche",
+      "0": "Sin coches",
+      "1": "Un coche",
+      ">5": "Algunos coches",
+      ">19": "Muchos coches",
+    }),
+  },
+} satisfies Dictionary;
+
+export default component1Content;
+```
+
+```jsx fileName="src/Component1/index.content.mjs" contentDeclarationFormat="esm"
+// Declaración de contenido para el componente 1
+import { t } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const component1Content = {
+  key: "component-1",
+  content: {
+    myTranslatedContent: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+    }),
+    numberOfCar: enu({
+      "<-1": "Menos de menos un coche",
+      "-1": "Menos un coche",
+      "0": "Sin coches",
+      "1": "Un coche",
+      ">5": "Algunos coches",
+      ">19": "Muchos coches",
+    }),
+  },
+};
+
+export default component1Content;
+```
+
+```jsx fileName="src/Component1/index.content.cjs" contentDeclarationFormat="commonjs"
+// Declaración de contenido para el componente 1
+const { t } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const component1Content = {
+  key: "component-1",
+  content: {
+    myTranslatedContent: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+    }),
+    numberOfCar: enu({
+      "<-1": "Menos de menos un coche",
+      "-1": "Menos un coche",
+      "0": "Sin coches",
+      "1": "Un coche",
+      ">5": "Algunos coches",
+      ">19": "Muchos coches",
+    }),
+  },
+};
+
+module.exports = component1Content;
+```
+
+```json fileName="src/Component1/index.content.json" codeFormat="json"
+{
+  "key": "component-1",
+  "content": {
+    "myTranslatedContent": {
+      "nodeType": "translation",
+      "translation": {
+        "en": "Hello World",
+        "fr": "Bonjour le monde",
+        "es": "Hola Mundo"
+      }
+    },
+    "numberOfCar": {
+      "nodeType": "enumeration",
+      "enumeration": {
+        "<-1": "Menos de menos un coche",
+        "-1": "Menos un coche",
+        "0": "Sin coches",
+        "1": "Un coche",
+        ">5": "Algunos coches",
+        ">19": "Muchos coches"
+      }
+    }
+  }
+}
+```
+
+### Utiliza el contenido en tu código
+
+Una vez que hayas declarado tu contenido, puedes usarlo en tu código. Aquí tienes un ejemplo de cómo usar el contenido en un componente React:
+
+```tsx {4,7} fileName="src/components/Component1Example.tsx" codeFormat="typescript"
+"use client";
+
+// Ejemplo de uso del contenido declarado
+import type { FC } from "react";
+import { useIntlayer } from "react-intlayer";
+
+export const Component1Example: FC = () => {
+  const { myTranslatedContent } = useIntlayer("component-1"); // Crear declaración de contenido relacionada
+
+  return (
+    <div>
+      <p>{myTranslatedContent}</p>
+    </div>
+  );
+};
+```
+
+```jsx {3,6} fileName="src/components/Component1Example.mjx" codeFormat="esm"
+"use client";
+
+// Ejemplo de uso del contenido declarado
+import { useIntlayer } from "react-intlayer";
+
+const Component1Example = () => {
+  const { myTranslatedContent } = useIntlayer("component-1"); // Crear declaración de contenido relacionada
+
+  return (
+    <div>
+      <p>{myTranslatedContent}</p>
+    </div>
+  );
+};
+```
+
+```jsx {3,6} fileName="src/components/Component1Example.csx" codeFormat="commonjs"
+"use client";
+
+// Ejemplo de uso del contenido declarado
+const { useIntlayer } = require("react-intlayer");
+
+const Component1Example = () => {
+  const { myTranslatedContent } = useIntlayer("component-1"); // Crear declaración de contenido relacionada
+
+  return (
+    <div>
+      <p>{myTranslatedContent}</p>
+    </div>
+  );
+};
+```
+
+## Domina la internacionalización de tu aplicación React
+
+Intlayer proporciona muchas características para ayudarte a internacionalizar tu aplicación React.
+
+**Para aprender más sobre estas características, consulta la guía [Internacionalización (i18n) en React con Intlayer y Vite y React](https://github.com/aymericzip/intlayer/blob/main/docs/es/intlayer_with_vite+react.md) para aplicaciones Vite y React, o la guía [Internacionalización (i18n) en React con Intlayer y React (CRA)](https://github.com/aymericzip/intlayer/blob/main/docs/es/intlayer_with_create_react_app.md) para aplicaciones creadas con React Create App.**
+
+## Funciones proporcionadas por el paquete `react-intlayer`
+
+El paquete `react-intlayer` también proporciona algunas funciones para ayudarte a internacionalizar tu aplicación.
+
+- [`t()`](https://github.com/aymericzip/intlayer/blob/main/docs/es/packages/react-intlayer/t.md)
+- [`useIntlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/es/packages/react-intlayer/useIntlayer.md)
+- [`useDictionary()`](https://github.com/aymericzip/intlayer/blob/main/docs/es/packages/react-intlayer/useDictionary.md)
+- [`useLocale()`](https://github.com/aymericzip/intlayer/blob/main/docs/es/packages/react-intlayer/useLocale.md)
+- [`useIntlayerAsync()`](https://github.com/aymericzip/intlayer/blob/main/docs/es/packages/react-intlayer/useIntlayerAsync.md)

package/es/packages/react-intlayer/t.md

@@ -0,0 +1,277 @@
+# Documentación: Función `t` en `react-intlayer`
+
+La función `t` en el paquete `react-intlayer` es una herramienta fundamental para la internacionalización en línea dentro de tu aplicación React. Te permite definir traducciones directamente dentro de tus componentes, haciendo que sea sencillo mostrar contenido localizado basado en el idioma actual.
+
+---
+
+## Descripción General
+
+La función `t` se utiliza para proporcionar traducciones para diferentes idiomas directamente en tus componentes. Al pasar un objeto que contiene traducciones para cada idioma soportado, `t` devuelve la traducción adecuada basada en el contexto de idioma actual en tu aplicación React.
+
+---
+
+## Características Principales
+
+- **Traducciones en Línea**: Ideal para texto rápido en línea que no requiere una declaración de contenido separada.
+- **Selección Automática de Idioma**: Devuelve automáticamente la traducción correspondiente al idioma actual.
+- **Soporte para TypeScript**: Proporciona seguridad de tipos y autocompletado cuando se usa con TypeScript.
+- **Fácil Integración**: Funciona perfectamente dentro de los componentes de React.
+
+---
+
+## Firma de la Función
+
+```typescript
+t<T extends string>(content: Record<LocalesValues, T>, locale?: Locales): string
+```
+
+### Parámetros
+
+- `translations`: Un objeto donde las claves son códigos de idioma (por ejemplo, `en`, `fr`, `es`) y los valores son las cadenas traducidas correspondientes.
+
+### Retorna
+
+- Una cadena que representa el contenido traducido para el idioma actual.
+
+---
+
+## Ejemplos de Uso
+
+### Uso Básico de `t` en un Componente
+
+```tsx fileName="src/components/ComponentExample.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { t } from "react-intlayer";
+
+export const ComponentExample: FC = () => {
+  return (
+    <div>
+      <p>
+        {t({
+          en: "This is an example of a component",
+          fr: "Ceci est un exemple de composant",
+          es: "Este es un ejemplo de componente",
+        })}
+      </p>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ComponentExample.mjx" codeFormat="esm"
+import { t } from "react-intlayer";
+
+const ComponentExample = () => {
+  return (
+    <div>
+      <p>
+        {t({
+          en: "This is an example of a component",
+          fr: "Ceci est un exemple de composant",
+          es: "Este es un ejemplo de componente",
+        })}
+      </p>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ComponentExample.csx" codeFormat="commonjs"
+const { t } = require("react-intlayer");
+
+const ComponentExample = () => {
+  return (
+    <div>
+      <p>
+        {t({
+          en: "This is an example of a component",
+          fr: "Ceci est un exemple de composant",
+          es: "Este es un ejemplo de componente",
+        })}
+      </p>
+    </div>
+  );
+};
+```
+
+### Traducciones en Línea en Atributos
+
+La función `t` es particularmente útil para traducciones en línea en atributos JSX. Al localizar atributos como `alt`, `title`, `href` o `aria-label`, puedes usar `t` directamente dentro del atributo.
+
+```jsx
+<button
+  aria-label={t({
+    en: "Submit",
+    fr: "Soumettre",
+    es: "Enviar",
+  })}
+>
+  {t({
+    en: "Submit",
+    fr: "Soumettre",
+    es: "Enviar",
+  })}
+  <img
+    src="/path/to/image"
+    alt={t({
+      en: "A beautiful scenery",
+      fr: "Un beau paysage",
+      es: "Un hermoso paisaje",
+    })}
+  />
+</button>
+```
+
+---
+
+## Temas Avanzados
+
+### Integración con TypeScript
+
+La función `t` es segura en cuanto a tipos cuando se usa con TypeScript, asegurando que se proporcionen todos los idiomas requeridos.
+
+```typescript codeFormat="typescript"
+import { t, type IConfigLocales } from "react-intlayer";
+
+const translations: IConfigLocales<string> = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+};
+
+const greeting = t(translations);
+```
+
+```javascript codeFormat="esm"
+import { t, type IConfigLocales } from "react-intlayer";
+
+/** @type {import('react-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+};
+
+const greeting = t(translations);
+```
+
+```javascript codeFormat="commonjs"
+const { t, type IConfigLocales } = require("react-intlayer");
+
+/** @type {import('react-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+};
+
+const greeting = t(translations);
+```
+
+### Detección de Idioma y Contexto
+
+En `react-intlayer`, el idioma actual se gestiona a través del `IntlayerProvider`. Asegúrate de que este proveedor envuelve tus componentes y que la propiedad `locale` se pasa correctamente.
+
+#### Ejemplo:
+
+```tsx fileName="src/app.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import type { Locales } from "intlayer";
+import { IntlayerProvider } from "react-intlayer";
+
+const App: FC<{ locale: Locales }> = ({ locale }) => (
+  <IntlayerProvider locale={locale}>
+    {/* Tus componentes aquí */}
+  </IntlayerProvider>
+);
+```
+
+```jsx fileName="src/app.mjx" codeFormat="esm"
+import { IntlayerProvider } from "react-intlayer";
+
+const App = ({ locale }) => (
+  <IntlayerProvider locale={locale}>
+    {/* Tus componentes aquí */}
+  </IntlayerProvider>
+);
+```
+
+```jsx fileName="src/app.csx" codeFormat="commonjs"
+const { IntlayerProvider } = require("react-intlayer");
+
+const App = ({ locale }) => (
+  <IntlayerProvider locale={locale}>
+    {/* Tus componentes aquí */}
+  </IntlayerProvider>
+);
+```
+
+---
+
+## Errores Comunes y Solución de Problemas
+
+### `t` Devuelve Undefined o Traducción Incorrecta
+
+- **Causa**: El idioma actual no está configurado correctamente o falta la traducción para el idioma actual.
+- **Solución**:
+  - Verifica que el `IntlayerProvider` esté configurado correctamente con el idioma adecuado.
+  - Asegúrate de que tu objeto de traducciones incluya todos los idiomas necesarios.
+
+### Faltan Traducciones en TypeScript
+
+- **Causa**: El objeto de traducciones no satisface los idiomas requeridos, lo que genera errores en TypeScript.
+- **Solución**: Usa el tipo `IConfigLocales` para garantizar la completitud de tus traducciones.
+
+```typescript codeFormat="typescript"
+const translations: IConfigLocales<string> = {
+  en: "Text",
+  fr: "Texte",
+  // es: 'Texto', // Falta 'es', lo que causará un error en TypeScript
+};
+
+const text = t(translations);
+```
+
+```javascript codeFormat="esm"
+const translations = {
+  en: "Text",
+  fr: "Texte",
+  // es: 'Texto', // Falta 'es', lo que causará un error en TypeScript
+};
+
+const text = t(translations);
+```
+
+```javascript codeFormat="commonjs"
+const { t, type IConfigLocales } = require("react-intlayer");
+
+/** @type {import('react-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Text",
+  fr: "Texte",
+  // es: 'Texto', // Falta 'es', lo que causará un error en TypeScript
+};
+
+const text = t(translations);
+```
+
+---
+
+## Consejos para un Uso Efectivo
+
+1. **Usa `t` para Traducciones Simples en Línea**: Ideal para traducir pequeños fragmentos de texto directamente dentro de tus componentes.
+2. **Prefiere `useIntlayer` para Contenido Estructurado**: Para traducciones más complejas y reutilización de contenido, define el contenido en archivos de declaración y usa `useIntlayer`.
+3. **Provisión Consistente de Idioma**: Asegúrate de que tu idioma se proporcione de manera consistente en toda tu aplicación a través del `IntlayerProvider`.
+4. **Aprovecha TypeScript**: Usa tipos de TypeScript para detectar traducciones faltantes y garantizar la seguridad de tipos.
+
+---
+
+## Conclusión
+
+La función `t` en `react-intlayer` es una herramienta poderosa y conveniente para gestionar traducciones en línea en tus aplicaciones React. Al integrarla de manera efectiva, mejoras las capacidades de internacionalización de tu aplicación, proporcionando una mejor experiencia para usuarios de todo el mundo.
+
+Para un uso más detallado y características avanzadas, consulta la [documentación de react-intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/es/intlayer_visual_editor.md).
+
+---
+
+**Nota**: Recuerda configurar correctamente tu `IntlayerProvider` para asegurarte de que el idioma actual se pase correctamente a tus componentes. Esto es crucial para que la función `t` devuelva las traducciones correctas.