Diccionarios

Los diccionarios ofrecen un enfoque tradicional para organizar las traducciones en objetos anidados con pares clave-valor. Aunque los <T> components son el enfoque recomendado, los diccionarios pueden ser útiles para migrar desde otras bibliotecas de i18n o cuando prefieras un almacenamiento de traducciones centralizado.

Recomendación: Usa los <T> components en proyectos nuevos. Los diccionarios se admiten principalmente para la migración y la compatibilidad con flujos de trabajo de traducción existentes.

Diccionario vs traducción por componentes

Patrón de diccionario

// dictionary.ts
export default {
  greetings: {
    hello: '¡Hola, mundo!',
    welcome: '¡Bienvenido, {name}!'
  }
};

// Component usage
function MyComponent() {
  const d = useTranslations();
  return <div>{d('greetings.hello')}</div>;
}

Patrón de componentes

// Uso directo del componente (recomendado)
function MyComponent() {
  return <T><div>¡Hola, mundo!</div></T>;
}

Compensaciones

Ventajas del diccionario

Almacenamiento centralizado - Todas las traducciones en un solo lugar
Estándar del sector - Patrón familiar de otras bibliotecas de i18n
Compatible con migraciones - Fácil portar traducciones existentes

Desventajas del diccionario

Complejidad - Requiere más configuración y ajuste inicial
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 diccionario

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

dictionary.ts

const dictionary = {
  greetings: {
    hello: '¡Hola, mundo!',
    welcome: '¡Bienvenido a nuestra app!'
  },
  navigation: {
    home: 'Inicio',
    about: 'Acerca de',
    contact: 'Contacto'
  }
};

export default dictionary;

O utiliza el formato JSON:

dictionary.json

{
  "greetings": {
    "hello": "¡Hola, mundo!",
    "welcome": "¡Bienvenido a nuestra app!"
  },
  "navigation": {
    "home": "Inicio", 
    "about": "Acerca de",
    "contact": "Contacto"
  }
}

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

Paso 2: Usar en componentes

El hook useTranslations te permite acceder a entradas del diccionario:

Componentes de cliente

import { useTranslations } from 'gt-next';

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

Componentes del servidor

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

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

Uso de variables

Agrega variables a las entradas del diccionario con la sintaxis {variable}:

dictionary.ts

const dictionary = {
  user: {
    greeting: '¡Hola, {name}!',
    itemCount: 'Tienes {count} artículos',
    orderTotal: 'Total: ${amount}'
  }
};

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

Uso de prefijos

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

dictionary.ts

const dictionary = {
  dashboard: {
    header: {
      welcome: '¡Bienvenido de nuevo!',
      lastLogin: 'Último inicio de sesión: {date}'
    },
    stats: {
      totalUsers: 'Usuarios totales: {count}',
      activeUsers: 'Usuarios activos: {count}'
    }
  }
};

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

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

Compatibilidad con varios idiomas

Traducción automática (recomendada)

La mayoría de los usuarios debería usar loadTranslations para generar automáticamente traducciones a partir del diccionario base:

dictionary.ts

const dictionary = {
  common: {
    save: 'Guardar',
    cancel: 'Cancelar',
    delete: 'Eliminar'
  },
  forms: {
    required: 'Este campo es obligatorio',
    email: 'Introduce un correo electrónico válido'
  }
};

export default dictionary;

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

src/loadTranslations.ts

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

withGTConfig 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 gtx-cli translate para generar traducciones para todos los idiomas configurados.

Files de traducción manual (Migración)

Para la migración desde otras bibliotecas de i18n o la gestión manual de traducciones, usa loadDictionary:

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/:

es.json

fr.json

de.json

Elige el enfoque adecuado: Usa loadTranslations para proyectos nuevos con generación automática de traducciones, o loadDictionary cuando migres archivos de traducción existentes.

Configuración para producción

Proceso de compilación

Agrega la traducción a tu pipeline de compilación:

package.json

{
  "scripts": {
    "build": "npx gtx-cli translate && <...TU_COMANDO_DE_COMPILACIÓN...>"
  }
}

Comportamiento en desarrollo vs producción

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

Combinación con componentes

Los dictionaries y componentes <T> pueden funcionar juntos:

function MixedApproach() {
  const d = useTranslations();
  
  return (
    <div>
      {/* Diccionario para cadenas simples */}
      <h1>{d('page.title')}</h1>
      
      {/* Componente T para JSX complejo */}
      <T>
        <p>Este es un <strong>mensaje complejo</strong> con <a href="/link">vínculos</a>.</p>
      </T>
      
      {/* Diccionario para etiquetas de formularios */}
      <label>{d('forms.email')}</label>
    </div>
  );
}

Próximos pasos

Guía de idiomas - Configura los idiomas compatibles y los ajustes de locale
Guía de contenido dinámico - Gestiona las necesidades de traducción en tiempo de ejecución
Referencia de API:
- useTranslations Hook
- getTranslations Function

Recomendación: Usa los <T> components en proyectos nuevos. Los diccionarios se admiten principalmente para la migración y la compatibilidad con flujos de trabajo de traducción existentes.

Diccionario vs traducción por componentes

Patrón de diccionario

// dictionary.ts
export default {
  greetings: {
    hello: '¡Hola, mundo!',
    welcome: '¡Bienvenido, {name}!'
  }
};

// Component usage
function MyComponent() {
  const d = useTranslations();
  return <div>{d('greetings.hello')}</div>;
}

Patrón de componentes

// Uso directo del componente (recomendado)
function MyComponent() {
  return <T><div>¡Hola, mundo!</div></T>;
}

Compensaciones

Ventajas del diccionario

Almacenamiento centralizado - Todas las traducciones en un solo lugar
Estándar del sector - Patrón familiar de otras bibliotecas de i18n
Compatible con migraciones - Fácil portar traducciones existentes

Desventajas del diccionario

Complejidad - Requiere más configuración y ajuste inicial
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 diccionario

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

dictionary.ts

const dictionary = {
  greetings: {
    hello: '¡Hola, mundo!',
    welcome: '¡Bienvenido a nuestra app!'
  },
  navigation: {
    home: 'Inicio',
    about: 'Acerca de',
    contact: 'Contacto'
  }
};

export default dictionary;

O utiliza el formato JSON:

dictionary.json

{
  "greetings": {
    "hello": "¡Hola, mundo!",
    "welcome": "¡Bienvenido a nuestra app!"
  },
  "navigation": {
    "home": "Inicio", 
    "about": "Acerca de",
    "contact": "Contacto"
  }
}

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

Paso 2: Usar en componentes

El hook useTranslations te permite acceder a entradas del diccionario:

Componentes de cliente

import { useTranslations } from 'gt-next';

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

Componentes del servidor

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

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

Uso de variables

Agrega variables a las entradas del diccionario con la sintaxis {variable}:

dictionary.ts

const dictionary = {
  user: {
    greeting: '¡Hola, {name}!',
    itemCount: 'Tienes {count} artículos',
    orderTotal: 'Total: ${amount}'
  }
};

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

Uso de prefijos

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

dictionary.ts

const dictionary = {
  dashboard: {
    header: {
      welcome: '¡Bienvenido de nuevo!',
      lastLogin: 'Último inicio de sesión: {date}'
    },
    stats: {
      totalUsers: 'Usuarios totales: {count}',
      activeUsers: 'Usuarios activos: {count}'
    }
  }
};

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

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

Compatibilidad con varios idiomas

Traducción automática (recomendada)

La mayoría de los usuarios debería usar loadTranslations para generar automáticamente traducciones a partir del diccionario base:

dictionary.ts

const dictionary = {
  common: {
    save: 'Guardar',
    cancel: 'Cancelar',
    delete: 'Eliminar'
  },
  forms: {
    required: 'Este campo es obligatorio',
    email: 'Introduce un correo electrónico válido'
  }
};

export default dictionary;

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

src/loadTranslations.ts

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

withGTConfig 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 gtx-cli translate para generar traducciones para todos los idiomas configurados.

Files de traducción manual (Migración)

Para la migración desde otras bibliotecas de i18n o la gestión manual de traducciones, usa loadDictionary:

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/:

es.json

fr.json

de.json

Elige el enfoque adecuado: Usa loadTranslations para proyectos nuevos con generación automática de traducciones, o loadDictionary cuando migres archivos de traducción existentes.

Configuración para producción

Proceso de compilación

Agrega la traducción a tu pipeline de compilación:

package.json

{
  "scripts": {
    "build": "npx gtx-cli translate && <...TU_COMANDO_DE_COMPILACIÓN...>"
  }
}

Comportamiento en desarrollo vs producción

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

Combinación con componentes

Los dictionaries y componentes <T> pueden funcionar juntos:

function MixedApproach() {
  const d = useTranslations();
  
  return (
    <div>
      {/* Diccionario para cadenas simples */}
      <h1>{d('page.title')}</h1>
      
      {/* Componente T para JSX complejo */}
      <T>
        <p>Este es un <strong>mensaje complejo</strong> con <a href="/link">vínculos</a>.</p>
      </T>
      
      {/* Diccionario para etiquetas de formularios */}
      <label>{d('forms.email')}</label>
    </div>
  );
}

Próximos pasos

Guía de idiomas - Configura los idiomas compatibles y los ajustes de locale
Guía de contenido dinámico - Gestiona las necesidades de traducción en tiempo de ejecución
Referencia de API:
- useTranslations Hook
- getTranslations Function

Recomendación: Usa los <T> components en proyectos nuevos. Los diccionarios se admiten principalmente para la migración y la compatibilidad con flujos de trabajo de traducción existentes.

Diccionario vs traducción por componentes

Patrón de diccionario

// dictionary.ts
export default {
  greetings: {
    hello: '¡Hola, mundo!',
    welcome: '¡Bienvenido, {name}!'
  }
};

// Component usage
function MyComponent() {
  const d = useTranslations();
  return <div>{d('greetings.hello')}</div>;
}

Patrón de componentes

// Uso directo del componente (recomendado)
function MyComponent() {
  return <T><div>¡Hola, mundo!</div></T>;
}

Compensaciones

Ventajas del diccionario

Almacenamiento centralizado - Todas las traducciones en un solo lugar
Estándar del sector - Patrón familiar de otras bibliotecas de i18n
Compatible con migraciones - Fácil portar traducciones existentes

Desventajas del diccionario

Complejidad - Requiere más configuración y ajuste inicial
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 diccionario

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

dictionary.ts

const dictionary = {
  greetings: {
    hello: '¡Hola, mundo!',
    welcome: '¡Bienvenido a nuestra app!'
  },
  navigation: {
    home: 'Inicio',
    about: 'Acerca de',
    contact: 'Contacto'
  }
};

export default dictionary;

O utiliza el formato JSON:

dictionary.json

{
  "greetings": {
    "hello": "¡Hola, mundo!",
    "welcome": "¡Bienvenido a nuestra app!"
  },
  "navigation": {
    "home": "Inicio", 
    "about": "Acerca de",
    "contact": "Contacto"
  }
}

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

Paso 2: Usar en componentes

El hook useTranslations te permite acceder a entradas del diccionario:

Componentes de cliente

import { useTranslations } from 'gt-next';

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

Componentes del servidor

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

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

Uso de variables

Agrega variables a las entradas del diccionario con la sintaxis {variable}:

dictionary.ts

const dictionary = {
  user: {
    greeting: '¡Hola, {name}!',
    itemCount: 'Tienes {count} artículos',
    orderTotal: 'Total: ${amount}'
  }
};

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

Uso de prefijos

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

dictionary.ts

const dictionary = {
  dashboard: {
    header: {
      welcome: '¡Bienvenido de nuevo!',
      lastLogin: 'Último inicio de sesión: {date}'
    },
    stats: {
      totalUsers: 'Usuarios totales: {count}',
      activeUsers: 'Usuarios activos: {count}'
    }
  }
};

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

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

Compatibilidad con varios idiomas

Traducción automática (recomendada)

La mayoría de los usuarios debería usar loadTranslations para generar automáticamente traducciones a partir del diccionario base:

dictionary.ts

const dictionary = {
  common: {
    save: 'Guardar',
    cancel: 'Cancelar',
    delete: 'Eliminar'
  },
  forms: {
    required: 'Este campo es obligatorio',
    email: 'Introduce un correo electrónico válido'
  }
};

export default dictionary;

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

src/loadTranslations.ts

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

withGTConfig 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 gtx-cli translate para generar traducciones para todos los idiomas configurados.

Files de traducción manual (Migración)

Para la migración desde otras bibliotecas de i18n o la gestión manual de traducciones, usa loadDictionary:

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/:

es.json

fr.json

de.json

Elige el enfoque adecuado: Usa loadTranslations para proyectos nuevos con generación automática de traducciones, o loadDictionary cuando migres archivos de traducción existentes.

Configuración para producción

Proceso de compilación

Agrega la traducción a tu pipeline de compilación:

package.json

{
  "scripts": {
    "build": "npx gtx-cli translate && <...TU_COMANDO_DE_COMPILACIÓN...>"
  }
}

Comportamiento en desarrollo vs producción

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

Combinación con componentes

Los dictionaries y componentes <T> pueden funcionar juntos:

function MixedApproach() {
  const d = useTranslations();
  
  return (
    <div>
      {/* Diccionario para cadenas simples */}
      <h1>{d('page.title')}</h1>
      
      {/* Componente T para JSX complejo */}
      <T>
        <p>Este es un <strong>mensaje complejo</strong> con <a href="/link">vínculos</a>.</p>
      </T>
      
      {/* Diccionario para etiquetas de formularios */}
      <label>{d('forms.email')}</label>
    </div>
  );
}

Próximos pasos

Guía de idiomas - Configura los idiomas compatibles y los ajustes de locale
Guía de contenido dinámico - Gestiona las necesidades de traducción en tiempo de ejecución
Referencia de API:
- useTranslations Hook
- getTranslations Function

Diccionarios

En esta página

Diccionarios

En esta página

Diccionarios

En esta página

GitHubDestacar en GitHub

GitHubDestacar en GitHub

Destacar en GitHub

Destacar en GitHub