# gt-react: General Translation React SDK: Diccionarios
URL: https://generaltranslation.com/es/docs/react/guides/dictionaries.mdx
---
title: Diccionarios
description: Cómo usar patrones tradicionales de traducción basados en diccionarios
---

{/* GENERADO AUTOMÁTICAMENTE: No lo edites directamente. En su lugar, edita la plantilla en content/docs-templates/. */}

Los diccionarios ofrecen una forma tradicional de organizar las traducciones en objetos anidados con pares clave-valor. Aunque los [componentes `<T>`](/docs/react/guides/t) son el enfoque recomendado, los diccionarios pueden resultar útiles al migrar desde otras bibliotecas de i18n o si prefieres almacenar las traducciones de forma centralizada.

<Callout>
  **Recomendación:** Usa los [componentes `<T>`](/docs/react/guides/t) en los proyectos nuevos. Los diccionarios se admiten principalmente para migraciones y para mantener la compatibilidad con flujos de trabajo de traducción existentes.
</Callout>


## Traducción por diccionario vs. por componentes

### Patrón de diccionario

```tsx
// dictionary.ts
export default {
  greetings: {
    hello: 'Hello, world!',
    welcome: 'Welcome, {name}!'
  }
};

// Uso del componente
function MyComponent() {
  const t = useTranslations();
  return <div>{t('greetings.hello')}</div>;
}
```


### Patrón de componente

```tsx
// Uso directo del componente - recomendado
function MyComponent() {
  return <T><div>Hello, world!</div></T>;
}
```


## Consideraciones

### Ventajas del diccionario

* **Almacenamiento centralizado** - Todas las traducciones en un solo lugar
* **Estándar del sector** - Un patrón conocido de otras bibliotecas de i18n
* **Fácil de migrar** - Fácil trasladar las traducciones existentes

### Desventajas de los diccionarios

* **Complejidad** - Requiere más configuración y preparación
* **Mantenibilidad** - Separar el contenido de su uso dificulta las actualizaciones
* **Depuración** - Es más difícil rastrear las traducciones hasta los componentes
* **Legibilidad** - Las claves no muestran el contenido real

## Guía rápida

### Paso 1: Crear un diccionario

Crea un archivo de diccionario en la raíz de tu proyecto o en el directorio `src`:

```ts title="dictionary.ts"
const dictionary = {
  greetings: {
    hello: 'Hello, world!',
    welcome: 'Welcome to our app!'
  },
  navigation: {
    home: 'Home',
    about: 'About',
    contact: 'Contact'
  }
};

export default dictionary;
```

O usa el formato JSON:

```json title="dictionary.json"
{
  "greetings": {
    "hello": "Hello, world!",
    "welcome": "Welcome to our app!"
  },
  "navigation": {
    "home": "Home", 
    "about": "About",
    "contact": "Contact"
  }
}
```

Luego se lo pasas a tu componente [`<GTProvider>`](/docs/react/api/components/gtprovider):

```jsx title="index.js" copy
import dictionary from "./dictionary.js";
import config from "./gt.config.json";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    {/* [!code highlight] */}
    <GTProvider {...config} dictionary={dictionary}>
      <App />
    </GTProvider>
  </StrictMode>
);
```


### Paso 2: Úsalo en los componentes

El hook [`useTranslations`](/docs/react/api/dictionary/use-translations) te permite acceder a las entradas del diccionario:

```tsx
import { useTranslations } from 'gt-react';

function MyComponent() {
  const t = useTranslations();
  
  return (
    <div>
      <h1>{t('greetings.hello')}</h1>
      <p>{t('greetings.welcome')}</p>
    </div>
  );
}
```


## Uso de variables

Añade variables a las entradas del diccionario con la sintaxis `{variable}`:

```ts title="dictionary.ts"
const dictionary = {
  user: {
    greeting: 'Hello, {name}!',
    itemCount: 'You have {count} items',
    orderTotal: 'Total: ${amount}'
  }
};
```

```tsx
function UserDashboard() {
  const t = useTranslations();
  
  return (
    <div>
      <h1>{t('user.greeting', { name: 'Alice' })}</h1>
      <p>{t('user.itemCount', { count: 5 })}</p>
      <p>{t('user.orderTotal', { amount: 99.99 })}</p>
    </div>
  );
}
```


## Uso de prefijos

Limita el acceso al diccionario a secciones específicas mediante prefijos:

```ts title="dictionary.ts"
const dictionary = {
  dashboard: {
    header: {
      welcome: 'Welcome back!',
      lastLogin: 'Last login: {date}'
    },
    stats: {
      totalUsers: 'Total Users: {count}',
      activeUsers: 'Active Users: {count}'
    }
  }
};
```

```tsx
function DashboardHeader() {
  // El prefijo limita el acceso a 'dashboard.header'
  const t = useTranslations('dashboard.header');
  
  return (
    <header>
      <h1>{t('welcome')}</h1> {/* -> dashboard.header.welcome */}
      <p>{t('lastLogin', { date: 'Today' })}</p> {/* -> dashboard.header.lastLogin */}
    </header>
  );
}

function DashboardStats() {
  // Prefijo diferente para la sección de estadísticas
  const t = useTranslations('dashboard.stats');
  
  return (
    <div>
      <p>{t('totalUsers', { count: 1000 })}</p> {/* -> dashboard.stats.totalUsers */}
      <p>{t('activeUsers', { count: 150 })}</p> {/* -> dashboard.stats.activeUsers */}
    </div>
  );
}
```


## Soporte para varios idiomas

### Traducción automática (recomendada)

La mayoría de los usuarios deberían usar [`loadTranslations`](/docs/react/api/config/load-translations) para generar automáticamente las traducciones a partir de tu diccionario base:

```ts title="dictionary.ts"  
const dictionary = {
  common: {
    save: 'Save',
    cancel: 'Cancel',
    delete: 'Delete'
  },
  forms: {
    required: 'This field is required',
    email: 'Please enter a valid email'
  }
};

export default dictionary;
```

Luego, crea una función `loadTranslations` para cargar los archivos de traducción generados:

```ts title="src/loadTranslations.ts"
export default async function loadTranslations(locale: string) {
  const translations = await import(`./_gt/${locale}.json`);
  return translations.default;
}
```

Pásalo a tu `<GTProvider>`:

```tsx title="src/index.tsx"
import loadTranslations from './loadTranslations';
import dictionary from './dictionary';

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

GT genera automáticamente traducciones a otros idiomas a partir de tu diccionario base. Ejecuta `npx gt translate` para generar traducciones para todos los idiomas configurados.


### Archivos de traducción manuales (migración)

Para migrar desde otras bibliotecas de i18n o desde la gestión manual de traducciones, usa [`loadDictionary`](/docs/react/api/config/load-dictionary):

```ts title="src/loadDictionary.ts"
export default async function loadDictionary(locale: string) {
  const translations = await import(`../public/locales/${locale}.json`);
  return translations.default;
}
```

Esto carga archivos de traducción JSON desde el directorio `public/locales/` de tu proyecto:

<Files>
  <Folder name="my-app" defaultOpen={true}>
    <Folder name="public" defaultOpen={true}>
      <Folder name="locales" defaultOpen={true}>
        <File name="es.json" />

        <File name="fr.json" />

        <File name="de.json" />
      </Folder>
    </Folder>

    <Folder name="src">
      <File name="loadDictionary.ts" />
    </Folder>
  </Folder>
</Files>

<Callout>
  **Elige el enfoque adecuado:** Usa [`loadTranslations`](/docs/react/api/config/load-translations) en proyectos nuevos con generación automática de traducciones, o [`loadDictionary`](/docs/react/api/config/load-dictionary) si vas a migrar archivos de traducción existentes.
</Callout>


## Configuración para producción

### Proceso de compilación

Integra la traducción en tu flujo de compilación:

```json title="package.json"
{
  "scripts": {
    "build": "npx gt translate && <...YOUR_BUILD_COMMAND...>"
  }
}
```


### Comportamiento en desarrollo frente a producción

* **Desarrollo**: Entradas del diccionario traducidas bajo demanda con la clave API de desarrollo
* **Producción**: Todas las traducciones del diccionario se generan previamente durante el paso de compilación

## Combinación con componentes

Los diccionarios y los [componentes `<T>`](/docs/react/guides/t) pueden usarse conjuntamente:

```tsx
function MixedApproach() {
  const t = useTranslations();
  
  return (
    <div>
      {/* Diccionario para cadenas simples */}
      <h1>{t('page.title')}</h1>
      
      {/* Componente T para JSX complejo */}
      <T>
        <p>This is a <strong>complex message</strong> with <a href="/link">links</a>.</p>
      </T>
      
      {/* Diccionario para etiquetas de formulario */}
      <label>{t('forms.email')}</label>
    </div>
  );
}
```


## Próximos pasos

<Callout>
  **Míralo en acción:** Echa un vistazo a la [aplicación de ejemplo del patrón de diccionario](https://github.com/gt-examples/dictionary-pattern) para ver una demostración funcional — [vista previa en vivo](https://dictionary-pattern.generaltranslation.dev).
</Callout>

* [Guía de idiomas](/docs/react/guides/languages) - Configura los idiomas compatibles y la configuración regional
* [Guía de contenido dinámico](/docs/key-concepts/dynamic-content) - Gestiona las necesidades de traducción en runtime
* Referencias de API:
  * [Hook `useTranslations`](/docs/react/api/dictionary/use-translations)