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-react 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 diccionario en tu aplicación React. Recorreremos 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 quieres traducir.

Agrega el siguiente contenido a tu archivo dictionary:

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

export default dictionary;

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

Luego lo pasas a tu componente <GTProvider>:

import dictionary from "./dictionary.js";
import config from "./gt.config.json";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <GTProvider {...config} dictionary={dictionary}>
      <App />
    </GTProvider>
  </StrictMode>
);

Paso 2: Referenciar el diccionario

Puedes acceder a las entradas del diccionario con el hook useTranslations(). Simplemente usa la función devuelta por el hook para acceder a las entradas del diccionario por clave.

import { useTranslations } from 'gt-react';

export default function MyComponent() {
  const d = useTranslations();
  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 i18n o ya tienes diccionarios para otros idiomas, puedes pasarlos a la función loadDictionary.

gt-react cargará automáticamente el diccionario correspondiente para la configuración regional solicitada cuando uses el hook useTranslations() o la función getDict().

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

Usando 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 { useTranslations } from 'gt-react';

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

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

Las cadenas de diccionario en gt-react soportan el formato de mensaje ICU, que también te permite formatear tus variables.

Prefijos

Además, con useTranslations(), 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 { useTranslations } from 'gt-react';

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

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

Consideraciones de producción

Despliegue a producción

Asegúrate de ejecutar el comando translate antes de desplegar a producción, para que todas las traducciones estén disponibles en tiempo de ejecución. Recomendamos agregarlo a 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 el despliegue de tu aplicación, consulta la guía de Deployment. Para más información sobre el comando, consulta la guía de referencia de CLI Tool.

Comportamiento: Desarrollo vs Producción

En desarrollo, la función devuelta por el hook useTranslations() 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, simplemente agrega una Dev API key a tu entorno.

En producción, la función d() traducirá el contenido en tiempo de construcción. Esto significa que tienes que 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 diccionarios 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 <T> component y cómo usarlo en tu aplicación React.
• Descubre cómo lanzar a producción con nuestra guía de despliegue.