Diccionarios

Descripción general

En esta guía, te presentaremos los diccionarios. Si lo deseas, siéntete libre de saltar entre las secciones de esta página según lo necesites. Cubriremos lo siguiente:

¿Qué es un diccionario?

Un diccionario es un objeto anidado con valores de tipo string que puede usarse para almacenar contenido traducible. Pueden almacenarse en un archivo .ts, .js o .json.

gt-next te permite usar diccionarios de forma independiente, o en conjunto con 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.
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 librerías de i18n.

Al mismo tiempo, tiene varias desventajas importantes:

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 y, en cambio, se almacena por separado. Esto hace que mantener y actualizar las traducciones sea mucho más difícil.
4. Depuración: Por la misma razón, los diccionarios son más difíciles de depurar que el componente <T>. Al intentar depurar un componente de React, tendrás que rastrear dónde se está utilizando el contenido en el diccionario, en lugar de simplemente buscarlo directamente en tu base de código.

Ambos patrones de diseño son compatibles con nuestra librería y no son mutuamente excluyentes. Puedes usar un diccionario junto con componentes <T>.

Nuestro consejo

Recomendamos usar el componente <T> por su simplicidad, especialmente si eres nuevo en la internacionalización (i18n). Ofrecemos soporte para diccionarios para quienes prefieren este patrón de diseño por experiencias previas 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 un diccionario en tu aplicación Next.js. Vamos a recorrer los siguientes pasos:

Paso 1: Crear un diccionario

El primer paso es crear un diccionario. Este es un archivo dictionary.[js|ts|json] que contiene todo el contenido que deseas traducir.

Agrega el siguiente contenido a tu archivo dictionary:

const dictionary = {
  greetings: {
    hello: 'Hello, World!'
  },
}

export default dictionary;

{
  "greetings": {
    "hello": "Hello, World!"
  }
}

La función withGTConfig() detectará automáticamente el archivo de diccionario en la raíz de tu proyecto o en el directorio src.

Paso 2: Referenciar el diccionario

Puedes acceder a las entradas del diccionario con el hook useDict() o la función getDict(). Simplemente usa la función que retorna el hook para acceder a las entradas del diccionario por clave.

import { useDict } from 'gt-next';

export default function MyComponent() {
  const d = useDict();
  return (
    <div>
      {d('greetings.hello')}
    </div>
  );
}

import { getDict } from 'gt-next';

export default async function MyComponent() {
  const d = await getDict();
  return (
    <div>
      {d('greetings.hello')}
    </div>
  );
}

Cargando 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 la localidad solicitada al usar el hook useDict() o la función getDict().

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

Uso de diccionarios

Variables

Puedes agregar variables a tu diccionario usando la sintaxis {variable}:

const dictionary = {
  greetings: {
    hello: 'Hello, {name}!',    // -> Hello, Alice!
    goodbye: 'Goodbye, {name}!' // -> Goodbye, Bob!
  },
}
export default dictionary;

import { useDict } from 'gt-next';

export default async function MyComponent() {
  const d = useDict();
  return (
    <div>
      {d('greetings.hello', { variables: { name: 'Alice' }})}
      {d('greetings.goodbye', { variables: { name: 'Bob' }})}
    </div>
  );
}

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

Prefijos

Además, con useDict(), 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 varios componentes.

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

import { useDict } from 'gt-next';

export default async function MyComponent() {
  // Todas las rutas de traducción como 'hello' serán precedidas por 'greetings.common.'
  const d = useDict('greetings.common'); 

  return (
    <div>
      {d('hello')} {/* hello -> greetings.common.hello */}
      {d('goodbye')} {/* goodbye -> greetings.common.goodbye */}
    </div>
  );
}

Consideraciones para producción

Despliegue en producción

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

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

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

Comportamiento: Desarrollo vs Producción

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

Para habilitar este comportamiento, solo agrega 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>. Se pueden usar junto con componentes <T> o de forma independiente.
• Las traducciones de diccionario ocurren en tiempo de compilación, por lo que debes agregar el comando translate a tu proceso de compilación.
• Los diccionarios se pueden usar 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 desplegar a producción con nuestra guía de despliegue.