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.

Ambos patrones de diseño son compatibles con nuestra biblioteca y no son mutuamente excluyentes. Puedes usar un diccionario junto con los 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 React. Recorreremos los siguientes pasos:

Paso 1: Crear un diccionario

El primer paso es crear un diccionario. Este es un archivo dictionary.js (.json) que contiene todo el contenido que deseas traducir.

Agrega el siguiente contenido a tu archivo dictionary.js:

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";
 
createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <GTProvider locales={['es', 'fr']} dictionary={dictionary}> // [!code highlight]
      <App />
    </GTProvider>
  </StrictMode>
);

Paso 2: Referenciar el diccionario

Puedes acceder a las entradas del diccionario con el hook useDict(). Solo usa la función d() para acceder a las entradas del diccionario por identificador.

import { useDict } from 'gt-react';
 
export default function MyComponent() {
 
  const d = useDict(); 
 
  return (
    <div>
      {d('greetings.hello')} // [!code highlight]
    </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-react 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 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-react';
 
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 deseas usar en múltiples componentes.

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

import { useDict } from 'gt-react';
 
export default async function MyComponent() {
  // Todas las rutas de traducción como 'hello' serán prefijadas con 'greetings'
  const d = useDict('greetings.common'); 
 
  return (
    <div>
      {d('hello')} {/* hello -> greetings.common.hello */}
      {d('goodbye')} {/* goodbye -> greetings.common.goodbye */}
    </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 agregarlo 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 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>. 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 React.
• Aprende cómo enviar a producción con nuestra guía de implementación.