Referencia de Diccionarios

Descripción general

En esta guía de referencia, te presentaremos el patrón de diccionario. Siéntete libre de navegar por esta página según sea necesario. Cubriremos lo siguiente:

• ¿Qué es un diccionario?
• Cómo usar diccionarios
• Carga de diccionarios para otros idiomas
• Uso de diccionarios
• Consideraciones para producción

¿Qué es un diccionario?

La Traducción General permite que el contenido traducible se almacene en un archivo de diccionario. Un diccionario es un objeto anidado con valores de cadena que puede utilizarse para almacenar contenido traducible. Este archivo de diccionario (.ts, .js, o .json) se utiliza luego para generar una traducción.

Los diccionarios pueden utilizarse de forma independiente o en conjunto con los componentes <T>.

Diccionario vs Componentes <T>

El patrón de diccionario tiene algunas ventajas sobre el componente <T>:

1. Almacenamiento centralizado: Los diccionarios almacenan todo el contenido traducible en un solo archivo, lo que facilita su gestión y actualización.
2. Precedente histórico: El patrón de diccionario es un patrón de diseño común en la industria y es utilizado por muchas otras bibliotecas.

Al mismo tiempo, también tiene algunas desventajas:

1. Complejidad: Los diccionarios son más complejos de configurar y usar que el componente <T>.
2. Legibilidad: Los diccionarios son menos legibles que el componente <T> porque el contenido no está en línea.
3. Mantenibilidad: Los diccionarios son más difíciles de mantener que el componente <T> porque el contenido no está en línea, sino que se almacena por separado. Esto hace que la depuración y el mantenimiento de las traducciones sea mucho más difícil.

Nuestra biblioteca admite ambos patrones de diseño y no son mutuamente excluyentes. Puedes usar un diccionario junto con componentes <T>.

Nuestro consejo

Recomendamos usar el componente <T> debido a su simplicidad, especialmente si eres nuevo en la internacionalización (i18n). Ofrecemos soporte para diccionarios para aquellos que prefieren este patrón de diseño por experiencias pasadas o para facilitar la integración con bases de código existentes.

Cómo usar diccionarios

En esta sección, te mostraremos cómo configurar una implementación básica de diccionario en tu aplicación Next.js. Recorreremos los siguientes pasos:

Paso 1: Crear un diccionario

El primer paso es crear un diccionario. Este es un archivo dictionary.js (.ts o .json) que contiene todo el contenido que deseas traducir. Crea el diccionario en tu directorio src/.

Si no estás utilizando una carpeta src/, también puedes especificar el directorio del diccionario en el archivo next.config.js.

Añade el siguiente contenido a tu archivo dictionary.js:

const dictionary = {
  greetings: {
    goodbye: 'Goodbye, World!'
  },
}
export default dictionary;

{
  "greetings": {
    "goodbye": "Goodbye, World!"
  }
}

Paso 2: Referenciar el diccionario

Hay varias formas de usar el diccionario, dependiendo del contexto donde estés intentando utilizarlo. Por ejemplo, si estás en un componente del lado del cliente, usa el hook useDict() y para componentes del lado del servidor usa await getDict().

Aquí hay un ejemplo de cómo usar el diccionario en un componente del lado del cliente:

"use client";
import { useDict } from 'gt-next/client';
 
export default function MyComponent() {
 
  const d = useDict(); // en el lado del cliente, usas el hook useDict
 
  return (
    <div>
      {d('greetings.hello')}
    </div>
  );
}

Y aquí hay un ejemplo de cómo acceder a las traducciones en un componente del lado del servidor:

import { getDict } from 'gt-next/server';
 
export default async function MyComponent() {
 
  const d = await getDict(); // en el lado del servidor, tienes que esperar una promesa
 
  return (
    <div>
      {d('greetings.hello')}
    </div>
  );
}

Carga de diccionarios para otros idiomas

Por defecto, los desarrolladores solo proporcionan un diccionario para el idioma predeterminado.

General Translation genera automáticamente diccionarios para otros idiomas y los carga con la función loadTranslations.

Sin embargo, si estás migrando desde otra biblioteca de i18n o ya tienes diccionarios para otros idiomas, puedes pasarlos a la función loadDictionary.

gt-next cargará automáticamente el diccionario correspondiente para el idioma solicitado cuando utilices el hook useDict() o la función getDict().

Consulta la Referencia de API para obtener más información.

Uso de diccionarios

Variables

Puedes añadir variables a tu diccionario utilizando la sintaxis {variable}:

const dictionary = {
  greetings: {
    hello: 'Hello, {name}!',
    goodbye: 'Goodbye, {name}!'
  },
}
export default dictionary;

import { getDict } from 'gt-next/server';
 
export default async function MyComponent() {
  const d = await getDict();
 
  return (
    <div>
      {d('greetings.hello', { variables: { name: 'World' }})}
      {d('greetings.goodbye', { variables: { name: 'World' }})}
    </div>
  );
}

Lee más sobre cómo añadir variables a tu diccionario en el tipo DictionaryTranslationOptions.

Prefijos

Además, con useDict() y getDict() puedes pasar un prefijo a la función para especificar una ruta compartida en el diccionario. Esto es útil si tienes una ruta compartida en tu diccionario que quieres usar en múltiples componentes.

const dictionary = {
  greetings: {
    common: {
      hello: 'Hello, World!',
      goodbye: 'Goodbye, World!'
    },
  },
}
export default dictionary;

import { getDict } from 'gt-next/server';
 
export default async function MyComponent() {
  // Todas las rutas de traducción como 'hello' tendrán el prefijo 'greetings'
  const d = await getDict('greetings.common'); 
 
  return (
    <div>
      {d('hello')} {/* hello -> greetings.common.hello */}
      {d('goodbye')} {/* goodbye -> greetings.common.goodbye */}
    </div>
  );
}

Subconjuntos con <GTProvider>

También puedes especificar un prefijo en el componente <GTProvider>. Esto pasará un subconjunto del diccionario al cliente, por lo que no será necesario cargar todo el diccionario. Esto solo se aplica a los componentes del lado del cliente.

import { GTProvider } from 'gt-next';
 
export default function RootLayout({ children }) {
    return (
        <html lang="en">
            <body>
                <GTProvider id="nested.dictionary.key"> // [!code highlight]
                    {children}
                </GTProvider> // [!code highlight]
            </body>
        </html>
    );
}

Aún tienes que especificar la ruta completa cuando haces referencia a una clave en el diccionario.

"use client";
 
import { useDict } from 'gt-next/client';
 
export default function MyComponent() {
  const d = useDict();
 
  return (
    <div>
      {d('nested.dictionary.key.greeting')} // [!code highlight]
    </div>
  );
}

Consideraciones de producción

Desplegando a producción

Asegúrate de ejecutar el comando de traducción antes de desplegar a producción, para que todas las traducciones estén disponibles en tiempo de ejecución. Recomendamos añadirlo a tu pipeline de CD o como parte de tu script de construcción.

{
  "scripts": {
    "build": "npx gtx-cli translate --languages fr es ja && <YOUR_BUILD_COMMAND>",
  }
}

¡Eso es todo! Has traducido exitosamente tu aplicación al francés, español y japonés.

Para una guía más detallada sobre cómo desplegar tu aplicación, por favor consulta la guía de Despliegue. Para más información sobre el comando, por favor consulta la guía de referencia de la Herramienta CLI.

Comportamiento: Desarrollo vs Producción

En desarrollo, la función d() traducirá las entradas del diccionario bajo demanda. Esto significa que cuando el componente se renderiza, realizará una traducción inmediatamente. Hacemos esto por conveniencia para facilitar el desarrollo con otros idiomas.

Para habilitar este comportamiento, solo añade una clave de API de desarrollo a tu entorno.

En producción, la función d() traducirá el contenido en tiempo de construcción. Esto significa que debes ejecutar el comando de traducción antes de desplegar tu aplicación.

Notas

• Los diccionarios son una alternativa al componente <T>. Pueden usarse junto con componentes <T> o de forma independiente.
• Las traducciones de diccionarios ocurren en el momento de la construcción, por lo que debes agregar el comando translate a tu proceso de construcción.
• Los diccionarios pueden usarse con prefijos para especificar un subconjunto del diccionario.

Próximos pasos

• Aprende sobre el componente <T> y cómo usarlo en tu aplicación Next.js.
• Aprende cómo enviar a producción con nuestra guía de despliegue.