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

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

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

## Traducción mediante diccionario vs. traducción mediante componente

### Patrón basado en 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** - Facilita portar las traducciones existentes

### Desventajas de los diccionarios

* **Complejidad** - Requieren más configuración y preparación previa
* **Mantenimiento** - Separar el contenido de su uso dificulta las actualizaciones
* **Depuración** - Es más difícil vincular las traducciones con los componentes
* **Legibilidad** - Las claves no muestran el contenido real

## Inicio rápido

### Paso 1: Crea 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"
  }
}
```

La función [`withGTConfig`](/docs/next/api/config/with-gt-config) detectará automáticamente el archivo de diccionario en la raíz de tu proyecto o en el directorio `src`.


### Paso 2: Úsalo en los componentes

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

#### Componentes del cliente

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

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


#### Componentes del servidor

```tsx
import { getTranslations } from 'gt-next/server';

async function MyServerComponent() {
  const d = await getTranslations();
  
  return (
    <div>
      <h1>{t('greetings.hello')}</h1>
      <p>{t('greetings.welcome')}</p>
    </div>
  );
}
```


## Uso de variables

Agrega 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

Restringe el acceso al diccionario a secciones específicas con 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/next/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;
```

Crea una función `loadTranslations` para cargar los archivos de traducción generados:

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

[`withGTConfig`](/docs/next/api/config/with-gt-config) detecta automáticamente el archivo `loadTranslations.[js|ts]` en tu directorio `src/` o en la raíz del proyecto.

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 manual (migración)

Para migrar desde otras bibliotecas de i18n o desde una gestión manual de las traducciones, usa [`loadDictionary`](/docs/next/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 tu directorio `public/locales/`:

<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/next/api/config/load-translations) en proyectos nuevos con generación automática de traducciones, o [`loadDictionary`](/docs/next/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 vs. producción

* **Desarrollo**: Las entradas del diccionario se traducen bajo demanda con la clave de API de desarrollo
* **Producción**: Todas las traducciones del diccionario se generan previamente durante la compilación

## Combinación con componentes

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

```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>
  **Velo en acción:** Echa un vistazo a la [aplicación de ejemplo del patrón basado en 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/next/guides/languages) - Configura los idiomas compatibles y la configuración regional
* [Guía de contenido dinámico](/docs/next/guides/dynamic-content) - Gestiona las necesidades de traducción en runtime
* Referencias de la API:
  * [Hook `useTranslations`](/docs/next/api/dictionary/use-translations)
  * [Función `getTranslations`](/docs/next/api/dictionary/get-translations)