@intlayer/docs 5.5.8

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

@@ -0,0 +1,237 @@
+# Integración con Next.js: Documentación del Hook `useIntlayer`
+
+El hook `useIntlayer` está diseñado para aplicaciones Next.js para obtener y gestionar contenido localizado de manera eficiente. Esta documentación se centrará en cómo utilizar el hook dentro de proyectos Next.js, asegurando prácticas adecuadas de localización.
+
+## Importando `useIntlayer` en Next.js
+
+Dependiendo de si estás trabajando en componentes del lado del cliente o del servidor en una aplicación Next.js, puedes importar el hook `useIntlayer` de la siguiente manera:
+
+- **Componente Cliente:**
+
+  ```typescript codeFormat="typescript"
+  import { useIntlayer } from "next-intlayer"; // Usado en componentes del lado del cliente
+  ```
+
+  ```javascript codeFormat="esm"
+  import { useIntlayer } from "next-intlayer"; // Usado en componentes del lado del cliente
+  ```
+
+  ```javascript codeFormat="commonjs"
+  const { useIntlayer } = require("next-intlayer"); // Usado en componentes del lado del cliente
+  ```
+
+- **Componente Servidor:**
+
+  ```tsx codeFormat="typescript"
+  import { useIntlayer } from "next-intlayer/server"; // Usado en componentes del lado del servidor
+  ```
+
+  ```javascript codeFormat="esm"
+  import { useIntlayer } from "next-intlayer/server"; // Usado en componentes del lado del servidor
+  ```
+
+  ```javascript codeFormat="commonjs"
+  const { useIntlayer } = require("next-intlayer/server"); // Usado en componentes del lado del servidor
+  ```
+
+## Parámetros
+
+1. **`key`**: Un identificador de cadena para la clave del diccionario de la que deseas recuperar contenido.
+2. **`locale`** (opcional): Una localización específica a usar. Si se omite, el hook utiliza por defecto la localización establecida en el contexto del cliente o servidor.
+
+## Archivos de Diccionario
+
+Es crucial que todas las claves de contenido estén definidas dentro de los archivos de declaración de contenido para evitar errores en tiempo de ejecución y garantizar la seguridad de tipos. Este enfoque también facilita la integración con TypeScript para la validación en tiempo de compilación.
+
+Las instrucciones para configurar los archivos de declaración de contenido están disponibles [aquí](https://github.com/aymericzip/intlayer/blob/main/docs/es/dictionary/get_started.md).
+
+## Ejemplo de Uso en Next.js
+
+Aquí se muestra cómo puedes implementar el hook `useIntlayer` dentro de una página Next.js para cargar dinámicamente contenido localizado basado en la localización actual de la aplicación:
+
+```tsx fileName="src/pages/[locale]/index.tsx" codeFormat="typescript"
+import { ClientComponentExample } from "@components/ClientComponentExample";
+import { ServerComponentExample } from "@components/ServerComponentExample";
+import { type NextPageIntlayer, IntlayerClientProvider } from "next-intlayer";
+import { useIntlayer, IntlayerServerProvider } from "next-intlayer/server";
+
+const HomePage: NextPageIntlayer = async ({ params }) => {
+  const { locale } = await params;
+
+  const content = useIntlayer("homepage", locale);
+
+  return (
+    <>
+      <p>{content.introduction}</p>
+      <IntlayerClientProvider locale={locale}>
+        <ClientComponentExample />
+      </IntlayerClientProvider>
+      <IntlayerServerProvider locale={locale}>
+        <ServerComponentExample />
+      </IntlayerServerProvider>
+    </>
+  );
+};
+```
+
+```jsx fileName="src/pages/[locale]/index.csx" codeFormat="esm"
+import { ClientComponentExample } from "@components/ClientComponentExample";
+import { ServerComponentExample } from "@components/ServerComponentExample";
+import { IntlayerClientProvider } from "next-intlayer";
+import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";
+
+const HomePage = ({ locale }) => {
+  const content = useIntlayer("homepage", locale);
+
+  return (
+    <>
+      <p>{content.introduction}</p>
+      <IntlayerClientProvider locale={locale}>
+        <ClientComponentExample />
+      </IntlayerClientProvider>
+      <IntlayerServerProvider locale={locale}>
+        <ServerComponentExample />
+      </IntlayerServerProvider>
+    </>
+  );
+};
+```
+
+```jsx fileName="src/components/ClientComponentExample.csx" codeFormat="commonjs"
+const {
+  ClientComponentExample,
+} = require("@components/ClientComponentExample");
+const {
+  ServerComponentExample,
+} = require("@components/ServerComponentExample");
+const { IntlayerClientProvider } = require("next-intlayer");
+const { useIntlayer } = require("next-intlayer/server");
+
+const HomePage = ({ locale }) => {
+  const content = useIntlayer("homepage", locale);
+
+  return (
+    <>
+      <p>{content.introduction}</p>
+      <IntlayerClientProvider locale={locale}>
+        <ClientComponentExample />
+      </IntlayerClientProvider>
+      <IntlayerServerProvider locale={locale}>
+        <ServerComponentExample />
+      </IntlayerServerProvider>
+    </>
+  );
+};
+```
+
+```tsx fileName="src/components/ClientComponentExample.tsx" codeFormat="typescript"
+"use-client";
+
+import type { FC } from "react";
+import { useIntlayer } from "next-intlayer";
+
+const ClientComponentExample: FC = () => {
+  const content = useIntlayer("component-content");
+
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ClientComponentExample.msx" codeFormat="esm"
+"use-client";
+
+import { useIntlayer } from "next-intlayer";
+
+const ServerComponentExample = () => {
+  const content = useIntlayer("component-content");
+
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ClientComponentExample.csx" codeFormat="commonjs"
+"use-client";
+
+const { useIntlayer } = require("next-intlayer");
+
+const ServerComponentExample = () => {
+  const content = useIntlayer("component-content");
+
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </div>
+  );
+};
+```
+
+```tsx fileName="src/components/ServerComponentExample.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useIntlayer } from "next-intlayer/server";
+
+const ServerComponentExample: FC = () => {
+  const content = useIntlayer("component-content");
+
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ServerComponentExample.mjx" codeFormat="esm"
+import { useIntlayer } from "next-intlayer/server";
+
+const ServerComponentExample = () => {
+  const content = useIntlayer("component-content");
+
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/ServerComponentExample.csx" codeFormat="commonjs"
+const { useIntlayer } = require("next-intlayer/server");
+
+const ServerComponentExample = () => {
+  const content = useIntlayer("component-content");
+
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </div>
+  );
+};
+```
+
+## Manejo de Localización de Atributos
+
+Para localizar atributos como `alt`, `title`, `href`, `aria-label`, etc., asegúrate de referenciar el contenido correctamente:
+
+```tsx
+<img src={content.image.src.value} alt={content.image.alt.value} />
+```
+
+## Más Información
+
+- **Editor Visual de Intlayer**: Aprende cómo usar el editor visual para una gestión más sencilla del contenido [aquí](https://github.com/aymericzip/intlayer/blob/main/docs/es/intlayer_visual_editor.md).
+
+Esta documentación describe el uso del hook `useIntlayer` específicamente dentro de entornos Next.js, proporcionando una solución robusta para gestionar la localización en tus aplicaciones Next.js.

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

@@ -0,0 +1,211 @@
+# Integración con Next.js: Documentación del Hook `useIntlayerAsync`
+
+El hook `useIntlayerAsync` extiende la funcionalidad de `useIntlayer` al no solo devolver diccionarios pre-renderizados, sino también al obtener actualizaciones de manera asincrónica, lo que lo hace ideal para aplicaciones que actualizan frecuentemente su contenido localizado después del renderizado inicial.
+
+## Resumen
+
+- **Carga Asincrónica de Diccionarios:**  
+  En el lado del cliente, `useIntlayerAsync` primero devuelve el diccionario de locales pre-renderizado (al igual que `useIntlayer`) y luego obtiene y fusiona asincrónicamente cualquier diccionario remoto nuevo disponible.
+- **Gestión del Estado de Progreso:**  
+  El hook también proporciona un estado `isLoading`, que indica cuándo se está obteniendo un diccionario remoto. Esto permite a los desarrolladores mostrar indicadores de carga o estados de esqueleto para una experiencia de usuario más fluida.
+
+## Configuración del Entorno
+
+Intlayer proporciona un sistema de gestión de contenido sin cabeza (CSM) que permite a personas no desarrolladoras gestionar y actualizar el contenido de la aplicación de manera fluida. Usando el panel intuitivo de Intlayer, tu equipo puede editar texto localizado, imágenes y otros recursos sin modificar directamente el código. Esto simplifica el proceso de gestión de contenido, fomenta la colaboración y asegura que las actualizaciones puedan realizarse de manera rápida y sencilla.
+
+Para comenzar con Intlayer, primero necesitas registrarte y obtener un token de acceso en [https://intlayer.org/dashboard](https://intlayer.org/dashboard). Una vez que tengas tus credenciales, agrégalas a tu archivo de configuración como se muestra a continuación:
+
+```typescript fileName="intlayer.config.ts" codeFormat="typescript"
+import type { IntlayerConfig } from "intlayer";
+
+export default {
+  // ...
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+  },
+} satisfies IntlayerConfig;
+```
+
+```javascript fileName="intlayer.config.mjs" codeFormat="esm"
+import { type IntlayerConfig } from "intlayer";
+
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  // ...
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+  },
+};
+
+export default config;
+```
+
+```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
+/** @type {import('intlayer').IntlayerConfig} */
+const config = {
+  // ...
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+  },
+};
+
+module.exports = config;
+```
+
+Después de configurar tus credenciales, puedes subir un nuevo diccionario de locales a Intlayer ejecutando:
+
+```bash
+npx intlayer dictionary push -d my-first-dictionary-key
+```
+
+Este comando sube tus diccionarios de contenido iniciales, haciéndolos disponibles para la obtención y edición asincrónica a través de la plataforma Intlayer.
+
+## Importando `useIntlayerAsync` en Next.js
+
+Dado que `useIntlayerAsync` está diseñado para componentes del **lado del cliente**, lo importarás desde el mismo punto de entrada del cliente que `useIntlayer`:
+
+```tsx codeFormat="typescript"
+"use client";
+
+import { useIntlayerAsync } from "next-intlayer";
+```
+
+```javascript codeFormat="esm"
+"use client";
+
+import { useIntlayerAsync } from "next-intlayer";
+```
+
+```javascript codeFormat="commonjs"
+"use client";
+
+const { useIntlayerAsync } = require("next-intlayer");
+```
+
+Asegúrate de que el archivo de importación esté anotado con `"use client"` en la parte superior, si estás usando el App Router de Next.js con componentes de servidor y cliente separados.
+
+## Parámetros
+
+1. **`key`**:  
+   **Tipo**: `DictionaryKeys`  
+   La clave del diccionario utilizada para identificar el bloque de contenido localizado. Esta clave debe estar definida en tus archivos de declaración de contenido.
+
+2. **`locale`** (opcional):  
+   **Tipo**: `Locales`  
+   El locale específico que deseas apuntar. Si se omite, el hook utiliza el locale del contexto del cliente.
+
+3. **`isRenderEditor`** (opcional, por defecto `true`):  
+   **Tipo**: `boolean`  
+   Determina si el contenido debe estar listo para renderizarse con la superposición del editor de Intlayer. Si se establece en `false`, los datos del diccionario devueltos excluirán las características específicas del editor.
+
+## Valor de Retorno
+
+El hook devuelve un objeto de diccionario que contiene contenido localizado identificado por `key` y `locale`. También incluye un booleano `isLoading` que indica si actualmente se está obteniendo un diccionario remoto.
+
+## Ejemplo de Uso en Next.js
+
+### Ejemplo de Componente del Lado del Cliente
+
+```tsx fileName="src/components/AsyncClientComponentExample.tsx" codeFormat="typescript"
+"use client";
+
+import { useEffect, type FC } from "react";
+import { useIntlayerAsync } from "next-intlayer";
+
+export const AsyncClientComponentExample: FC = () => {
+  const { title, description, isLoading } = useIntlayerAsync("async-component");
+
+  useEffect(() => {
+    if (isLoading) {
+      console.log("El contenido se está cargando...");
+    }
+  }, [isLoading]);
+
+  return (
+    <div>
+      <h1>{title.value}</h1>
+      <p>{description.value}</p>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/AsyncClientComponentExample.mjx" codeFormat="esm"
+"use client";
+
+import { useEffect } from "react";
+import { useIntlayerAsync } from "next-intlayer";
+
+const AsyncClientComponentExample = () => {
+  const { title, description, isLoading } = useIntlayerAsync("async-component");
+
+  useEffect(() => {
+    if (isLoading) {
+      console.log("El contenido se está cargando...");
+    }
+  }, [isLoading]);
+
+  return (
+    <div>
+      <h1>{title.value}</h1>
+      <p>{description.value}</p>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/AsyncClientComponentExample.csx" codeFormat="commonjs"
+"use client";
+
+const { useEffect } = require("react");
+const { useIntlayerAsync } = require("next-intlayer");
+
+const AsyncClientComponentExample = () => {
+  const { title, description, isLoading } = useIntlayerAsync("async-component");
+
+  useEffect(() => {
+    if (isLoading) {
+      console.log("El contenido se está cargando...");
+    }
+  }, [isLoading]);
+
+  return (
+    <div>
+      <h1>{title.value}</h1>
+      <p>{description.value}</p>
+    </div>
+  );
+};
+```
+
+**Puntos Clave:**
+
+- En el renderizado inicial, `title` y `description` provienen del diccionario de locales pre-renderizado.
+- Mientras `isLoading` es `true`, se realiza una solicitud remota en segundo plano para obtener un diccionario actualizado.
+- Una vez que se completa la obtención, `title` y `description` se actualizan con el contenido más reciente, y `isLoading` vuelve a `false`.
+
+## Gestión de Atributos Localizados
+
+Al igual que con `useIntlayer`, puedes recuperar valores de atributos localizados para varias propiedades HTML (por ejemplo, `alt`, `title`, `aria-label`):
+
+```tsx
+<img src={title.image.src.value} alt={title.image.alt.value} />
+```
+
+## Archivos de Diccionario
+
+Todas las claves de contenido deben definirse en tus archivos de declaración de contenido para garantizar la seguridad de tipos y prevenir errores en tiempo de ejecución. Estos archivos permiten la validación de TypeScript, asegurando que siempre hagas referencia a claves y locales existentes.
+
+Las instrucciones para configurar archivos de declaración de contenido están disponibles [aquí](https://github.com/aymericzip/intlayer/blob/main/docs/es/dictionary/get_started.md).
+
+## Más Información
+
+- **Editor Visual de Intlayer:**  
+  Integra con el editor visual de Intlayer para gestionar y editar contenido directamente desde la interfaz de usuario. Más detalles [aquí](https://github.com/aymericzip/intlayer/blob/main/docs/es/intlayer_visual_editor.md).
+
+---
+
+**En resumen**, `useIntlayerAsync` es un poderoso hook del lado del cliente diseñado para mejorar la experiencia del usuario y mantener la frescura del contenido al combinar diccionarios pre-renderizados con actualizaciones asincrónicas de diccionarios. Aprovechando `isLoading` y las declaraciones de contenido basadas en TypeScript, puedes integrar contenido dinámico y localizado sin problemas en tus aplicaciones Next.js.

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

@@ -0,0 +1,105 @@
+# Integración con Next.js: Documentación del Hook `useLocale` para `next-intlayer`
+
+Esta sección ofrece documentación detallada sobre el hook `useLocale` diseñado para aplicaciones Next.js dentro de la biblioteca `next-intlayer`. Está diseñado para manejar cambios de localización y enrutamiento de manera eficiente.
+
+## Importando `useLocale` en Next.js
+
+Para utilizar el hook `useLocale` en tu aplicación Next.js, impórtalo como se muestra a continuación:
+
+```javascript
+import { useLocale } from "next-intlayer"; // Usado para gestionar localizaciones y enrutamiento en Next.js
+```
+
+## Uso
+
+A continuación, se muestra cómo implementar el hook `useLocale` dentro de un componente de Next.js:
+
+```tsx fileName="src/components/LocaleSwitcher.tsx" codeFormat="typescript"
+"use client";
+
+import type { FC } from "react";
+import { Locales } from "intlayer";
+import { useLocale } from "next-intlayer";
+
+const LocaleSwitcher: FC = () => {
+  const { locale, defaultLocale, availableLocales, setLocale } = useLocale();
+
+  return (
+    <div>
+      <h1>Localización Actual: {locale}</h1>
+      <p>Localización Predeterminada: {defaultLocale}</p>
+      <select value={locale} onChange={(e) => setLocale(e.target.value)}>
+        {availableLocales.map((loc) => (
+          <option key={loc} value={loc}>
+            {loc}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/LocaleSwitcher.mjx" codeFormat="esm"
+"use client";
+
+import { Locales } from "intlayer";
+import { useLocale } from "next-intlayer";
+
+const LocaleSwitcher = () => {
+  const { locale, defaultLocale, availableLocales, setLocale } = useLocale();
+
+  return (
+    <div>
+      <h1>Localización Actual: {locale}</h1>
+      <p>Localización Predeterminada: {defaultLocale}</p>
+      <select value={locale} onChange={(e) => setLocale(e.target.value)}>
+        {availableLocales.map((loc) => (
+          <option key={loc} value={loc}>
+            {loc}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+};
+```
+
+```jsx fileName="src/components/LocaleSwitcher.csx" codeFormat="commonjs"
+"use client";
+
+const { Locales } = require("intlayer");
+const { useLocale } = require("next-intlayer");
+
+const LocaleSwitcher = () => {
+  const { locale, defaultLocale, availableLocales, setLocale } = useLocale();
+
+  return (
+    <div>
+      <h1>Localización Actual: {locale}</h1>
+      <p>Localización Predeterminada: {defaultLocale}</p>
+      <select value={locale} onChange={(e) => setLocale(e.target.value)}>
+        {availableLocales.map((loc) => (
+          <option key={loc} value={loc}>
+            {loc}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+};
+```
+
+## Parámetros y Valores de Retorno
+
+Cuando invocas el hook `useLocale`, devuelve un objeto que contiene las siguientes propiedades:
+
+- **`locale`**: La localización actual establecida en el contexto de React.
+- **`defaultLocale`**: La localización principal definida en la configuración.
+- **`availableLocales`**: Una lista de todas las localizaciones disponibles según lo definido en la configuración.
+- **`setLocale`**: Una función para cambiar la localización de la aplicación y actualizar la URL en consecuencia. Se encarga de las reglas de prefijo, ya sea para agregar la localización al camino o no, según la configuración. Utiliza `useRouter` de `next/navigation` para funciones de navegación como `push` y `refresh`.
+- **`pathWithoutLocale`**: Una propiedad calculada que devuelve el camino sin la localización. Es útil para comparar URLs. Por ejemplo, si la localización actual es `fr`, y la URL es `fr/my_path`, el camino sin localización es `/my_path`. Utiliza `usePathname` de `next/navigation` para obtener el camino actual.
+
+## Conclusión
+
+El hook `useLocale` de `next-intlayer` es una herramienta crucial para gestionar localizaciones en aplicaciones Next.js. Ofrece un enfoque integrado para adaptar tu aplicación a múltiples localizaciones manejando el almacenamiento de localización, la gestión del estado y las modificaciones de URL de manera fluida.

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

@@ -0,0 +1,3 @@
+this doc will be automatically generated translated from the english doc
+
+see /docs/en/packages/preact-intlayer/index.md