@intlayer/docs 5.5.8

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

@@ -0,0 +1,325 @@
+# Documentación: Función `t` en `next-intlayer`
+
+La función `t` en el paquete `next-intlayer` es una herramienta fundamental para la internacionalización en línea dentro de tu aplicación Next.js. 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 apropiada basada en el contexto del idioma actual en tu aplicación Next.js.
+
+---
+
+## Características Clave
+
+- **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 tanto en componentes del cliente como del servidor en Next.js.
+
+---
+
+## 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
+
+### Usando `t` en un Componente del Cliente
+
+Asegúrate de incluir la directiva `'use client';` en la parte superior de tu archivo de componente al usar `t` en un componente del lado del cliente.
+
+```tsx codeFormat="typescript"
+"use client";
+
+import type { FC } from "react";
+import { t } from "next-intlayer";
+
+export const ClientComponentExample: FC = () => (
+  <p>
+    {t({
+      en: "This is the content of a client component example",
+      fr: "Ceci est le contenu d'un exemple de composant client",
+      es: "Este es el contenido de un ejemplo de componente cliente",
+    })}
+  </p>
+);
+```
+
+```javascript codeFormat="esm"
+import { t } from "next-intlayer";
+
+const ClientComponentExample = () => (
+  <p>
+    {t({
+      en: "This is the content of a client component example",
+      fr: "Ceci est le contenu d'un exemple de composant client",
+      es: "Este es el contenido de un ejemplo de componente cliente",
+    })}
+  </p>
+);
+```
+
+```javascript codeFormat="commonjs"
+const { t } = require("next-intlayer");
+
+const ClientComponentExample = () => (
+  <p>
+    {t({
+      en: "This is the content of a client component example",
+      fr: "Ceci est le contenu d'un exemple de composant client",
+      es: "Este es el contenido de un ejemplo de componente cliente",
+    })}
+  </p>
+);
+```
+
+### Usando `t` en un Componente del Servidor
+
+```tsx codeFormat="typescript"
+import type { FC } from "react";
+import { t } from "next-intlayer/server";
+
+export const ServerComponentExample: FC = () => (
+  <p>
+    {t({
+      en: "This is the content of a server component example",
+      fr: "Ceci est le contenu d'un exemple de composant serveur",
+      es: "Este es el contenido de un ejemplo de componente servidor",
+    })}
+  </p>
+);
+```
+
+```javascript codeFormat="esm"
+import { t } from "next-intlayer/server";
+
+const ServerComponentExample = () => (
+  <p>
+    {t({
+      en: "This is the content of a server component example",
+      fr: "Ceci est le contenu d'un exemple de composant serveur",
+      es: "Este es el contenido de un ejemplo de componente servidor",
+    })}
+  </p>
+);
+```
+
+```javascript codeFormat="commonjs"
+const { t } = require("next-intlayer/server");
+
+const ServerComponentExample = () => (
+  <p>
+    {t({
+      en: "This is the content of a server component example",
+      fr: "Ceci est le contenu d'un exemple de composant serveur",
+      es: "Este es el contenido de un ejemplo de componente servidor",
+    })}
+  </p>
+);
+```
+
+### 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 para tipos cuando se usa con TypeScript, asegurando que se proporcionen todos los idiomas requeridos.
+
+```typescript codeFormat="typescript"
+import type { IConfigLocales } from "intlayer";
+import { t } from "next-intlayer";
+
+const translations: IConfigLocales<string> = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+};
+
+const greeting = t(translations);
+```
+
+```javascript codeFormat="esm"
+import type { IConfigLocales } from "intlayer";
+import { t } from "next-intlayer";
+
+/** @type {import('next-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+};
+
+const greeting = t(translations);
+```
+
+```javascript codeFormat="commonjs"
+const { t } = require("next-intlayer");
+
+/** @type {import('next-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Welcome",
+  fr: "Bienvenue",
+  es: "Bienvenido",
+};
+
+const greeting = t(translations);
+```
+
+### Detección de Idioma y Contexto
+
+En `next-intlayer`, el idioma actual se gestiona a través de proveedores de contexto: `IntlayerClientProvider` y `IntlayerServerProvider`. Asegúrate de que estos proveedores envuelvan tus componentes y que la propiedad `locale` se pase correctamente.
+
+#### Ejemplo:
+
+```tsx codeFormat="typescript"
+import type { FC } from "react";
+import type { Locales } from "intlayer";
+import { IntlayerClientProvider } from "next-intlayer";
+import { IntlayerServerProvider } from "next-intlayer/server";
+
+const Page: FC<{ locale: Locales }> = ({ locale }) => (
+  <IntlayerServerProvider locale={locale}>
+    <IntlayerClientProvider locale={locale}>
+      {/* Tus componentes aquí */}
+    </IntlayerClientProvider>
+  </IntlayerServerProvider>
+);
+```
+
+```javascript codeFormat="esm"
+import { IntlayerClientProvider } from "next-intlayer";
+import { IntlayerServerProvider } from "next-intlayer/server";
+
+const Page = ({ locale }) => (
+  <IntlayerServerProvider locale={locale}>
+    <IntlayerClientProvider locale={locale}>
+      {/* Tus componentes aquí */}
+    </IntlayerClientProvider>
+  </IntlayerServerProvider>
+);
+```
+
+```javascript codeFormat="commonjs"
+const { IntlayerClientProvider } = require("next-intlayer");
+const { IntlayerServerProvider } = require("next-intlayer/server");
+
+const Page = ({ locale }) => (
+  <IntlayerServerProvider locale={locale}>
+    <IntlayerClientProvider locale={locale}>
+      {/* Tus componentes aquí */}
+    </IntlayerClientProvider>
+  </IntlayerServerProvider>
+);
+```
+
+---
+
+## 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 `IntlayerClientProvider` o `IntlayerServerProvider` esté configurado correctamente con el idioma apropiado.
+  - 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 [!code error]
+};
+
+const text = t(translations);
+```
+
+```javascript codeFormat="esm"
+const translations = {
+  en: "Text",
+  fr: "Texte",
+  // es: 'Texto', // Falta 'es', lo que causará un error en TypeScript [!code error]
+};
+
+const text = t(translations);
+```
+
+```javascript codeFormat="commonjs"
+const { t } = require("next-intlayer");
+
+/** @type {import('next-intlayer').IConfigLocales<string>} */
+const translations = {
+  en: "Text",
+  fr: "Texte",
+  // es: 'Texto', // Falta 'es', lo que causará un error en TypeScript [!code error]
+};
+
+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 contenido en archivos de declaración y usa `useIntlayer`.
+3. **Provisión Consistente de Idioma**: Asegúrate de que tu idioma se proporcione consistentemente en toda tu aplicación a través de los proveedores apropiados.
+4. **Aprovecha TypeScript**: Usa tipos de TypeScript para detectar traducciones faltantes y garantizar la seguridad de tipos.
+
+---
+
+## Conclusión
+
+La función `t` en `next-intlayer` es una herramienta poderosa y conveniente para gestionar traducciones en línea en tus aplicaciones Next.js. 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 next-intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/es/intlayer_visual_editor.md).
+
+---
+
+**Nota**: Recuerda configurar correctamente tu `IntlayerClientProvider` y `IntlayerServerProvider` para garantizar que el idioma actual se pase correctamente a tus componentes. Esto es crucial para que la función `t` devuelva las traducciones correctas.

package/es/packages/next-intlayer/useDictionary.md

@@ -0,0 +1,242 @@
+# Integración con React: Documentación del Hook `useDictionary`
+
+Esta sección proporciona una guía detallada sobre cómo usar el hook `useDictionary` dentro de aplicaciones React, permitiendo un manejo eficiente de contenido localizado sin un editor visual.
+
+## Importando `useDictionary` en React
+
+El hook `useDictionary` puede integrarse en aplicaciones React importándolo según el contexto:
+
+- **Componente del Cliente:**
+
+  ```typescript codeFormat="typescript"
+  import { useDictionary } from "next-intlayer"; // Usado en componentes React del lado del cliente
+  ```
+
+  ```javascript codeFormat="esm"
+  import { useDictionary } from "next-intlayer"; // Usado en componentes React del lado del cliente
+  ```
+
+  ```javascript codeFormat="commonjs"
+  const { useDictionary } = require("next-intlayer"); // Usado en componentes React del lado del cliente
+  ```
+
+- **Componente del Servidor:**
+
+  ```typescript codeFormat="typescript"
+  import { useDictionary } from "next-intlayer/server"; // Usado en componentes React del lado del servidor
+  ```
+
+  ```javascript codeFormat="esm"
+  import { useDictionary } from "next-intlayer/server"; // Usado en componentes React del lado del servidor
+  ```
+
+  ```javascript codeFormat="commonjs"
+  const { useDictionary } = require("next-intlayer/server"); // Usado en componentes React del lado del servidor
+  ```
+
+## Parámetros
+
+El hook acepta dos parámetros:
+
+1. **`dictionary`**: Un objeto de diccionario declarado que contiene contenido localizado para claves específicas.
+2. **`locale`** (opcional): La localización deseada. Por defecto, utiliza la localización del contexto actual si no se especifica.
+
+## Diccionario
+
+Todos los objetos de diccionario deben declararse en archivos de contenido estructurado para garantizar la seguridad de tipos y prevenir errores en tiempo de ejecución. Puedes encontrar las instrucciones de configuración [aquí](https://github.com/aymericzip/intlayer/blob/main/docs/es/dictionary/get_started.md). Aquí tienes un ejemplo de declaración de contenido:
+
+```typescript fileName="component.content.ts" codeFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const exampleContent = {
+  key: "component-example",
+  content: {
+    title: t({
+      en: "Client Component Example",
+      fr: "Exemple de composant client",
+      es: "Ejemplo de componente cliente",
+    }),
+    content: t({
+      en: "This is the content of a client component example",
+      fr: "Ceci est le contenu d'un exemple de composant client",
+      es: "Este es el contenido de un ejemplo de componente cliente",
+    }),
+  },
+} satisfies Dictionary;
+
+export default exampleContent;
+```
+
+```javascript fileName="component.content.mjs" contentDeclarationFormat="esm"
+import { t } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const exampleContent = {
+  key: "component-example",
+  content: {
+    title: t({
+      en: "Client Component Example",
+      fr: "Exemple de composant client",
+      es: "Ejemplo de componente cliente",
+    }),
+    content: t({
+      en: "This is the content of a client component example",
+      fr: "Ceci est le contenu d'un exemple de composant client",
+      es: "Este es el contenido de un ejemplo de componente cliente",
+    }),
+  },
+};
+
+export default exampleContent;
+```
+
+```javascript fileName="component.content.cjs" contentDeclarationFormat="commonjs"
+const { t } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+const exampleContent = {
+  key: "component-example",
+  content: {
+    title: t({
+      en: "Client Component Example",
+      fr: "Exemple de composant client",
+      es: "Ejemplo de componente cliente",
+    }),
+    content: t({
+      en: "This is the content of a client component example",
+      fr: "Ceci est le contenu d'un exemple de composant client",
+      es: "Este es el contenido de un ejemplo de componente cliente",
+    }),
+  },
+};
+
+module.exports = exampleContent;
+```
+
+## Ejemplo de Uso en un Componente Cliente de React
+
+A continuación, se muestra un ejemplo de cómo usar el hook `useDictionary` en un componente React:
+
+```tsx fileName="ClientComponentExample.tsx" codeFormat="typescript"
+"use client";
+
+import type { FC } from "react";
+import { useDictionary } from "next-intlayer";
+import clientComponentExampleContent from "./component.content";
+
+const ClientComponentExample: FC = () => {
+  const { title, content } = useDictionary(clientComponentExampleContent);
+
+  return (
+    <div>
+      <h1>{title}</h1>
+      <p>{content}</p>
+    </div>
+  );
+};
+```
+
+```javascript fileName="ClientComponentExample.mjs" codeFormat="esm"
+"use client";
+
+import type { FC } from "react";
+import { useDictionary } from "next-intlayer";
+import exampleContent from "./component.content";
+
+const ClientComponentExample: FC = () => {
+  const { title, content } = useDictionary(exampleContent);
+
+  return (
+    <div>
+      <h1>{title}</h1>
+      <p>{content}</p>
+    </div>
+  );
+};
+```
+
+```javascript fileName="ClientComponentExample.cjs" codeFormat="commonjs"
+"use client";
+
+const { useDictionary } = require("next-intlayer");
+const exampleContent = require("./component.content");
+
+const ClientComponentExample = () => {
+  const { title, content } = useDictionary(exampleContent);
+
+  return (
+    <div>
+      <h1>{title}</h1>
+      <p>{content}</p>
+    </div>
+  );
+};
+```
+
+## Ejemplo de Uso en un Componente Servidor de React
+
+Si estás utilizando el hook `useDictionary` fuera del `IntlayerServerProvider`, la localización debe proporcionarse explícitamente como un parámetro al renderizar el componente:
+
+```tsx fileName="ServerComponentExample.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useDictionary } from "next-intlayer/server";
+import clientComponentExampleContent from "./component.content";
+
+const ServerComponentExample: FC = () => {
+  const { content } = useDictionary(clientComponentExampleContent);
+
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.content}</p>
+    </div>
+  );
+};
+```
+
+```javascript fileName="ServerComponentExample.mjs" codeFormat="esm"
+import { useDictionary } from "next-intlayer/server";
+import clientComponentExampleContent from "./component.content";
+
+const ServerComponentExample = () => {
+  const { content } = useDictionary(clientComponentExampleContent);
+
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.content}</p>
+    </div>
+  );
+};
+```
+
+```javascript fileName="ServerComponentExample.cjs" codeFormat="commonjs"
+import { useDictionary } from "next-intlayer/server";
+import clientComponentExampleContent from "./component.content";
+
+const ServerComponentExample = () => {
+  const { content } = useDictionary(clientComponentExampleContent);
+
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.content}</p>
+    </div>
+  );
+};
+```
+
+## Notas sobre Atributos
+
+A diferencia de las integraciones que utilizan editores visuales, atributos como `buttonTitle.value` no aplican aquí. En su lugar, accede directamente a las cadenas localizadas como se declaran en tu contenido.
+
+```jsx
+<button title={content.title}>{content.content}</button>
+```
+
+## Consejos Adicionales
+
+- **Seguridad de Tipos**: Siempre utiliza `Dictionary` para definir tus diccionarios y garantizar la seguridad de tipos.
+- **Actualizaciones de Localización**: Al actualizar contenido, asegúrate de que todas las localizaciones sean consistentes para evitar traducciones faltantes.
+
+Esta documentación se centra en la integración del hook `useDictionary`, proporcionando un enfoque simplificado para gestionar contenido localizado sin depender de funcionalidades de editores visuales.