GitHub

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

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

Traducción con diccionario vs. con 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>;
}

Compromisos

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 de migrar traducciones existentes

Desventajas del diccionario

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

Comienzo rápido

Paso 1: Crear diccionario

Crea un archivo diccionario en la raíz de tu 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 usa 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 dictionary en la raíz del proyecto o en el directorio src.

Paso 2: Uso en componentes

El hook useTranslations te permite acceder a entradas del diccionario:

Componentes del 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

Añade 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

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

dictionary.ts

const dictionary = {
  dashboard: {
    header: {
      welcome: '¡Bienvenido de nuevo!',
      lastLogin: 'Último acceso: {date}'
    },
    stats: {
      totalUsers: 'Total de usuarios: {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: 'Today' })}</p> {/* -> dashboard.header.lastLogin */}
    </header>
  );
}

function DashboardStats() {
  // 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ían usar loadTranslations para generar automáticamente traducciones a partir de su diccionario base:

dictionary.ts

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

export default dictionary;

Crea una función loadTranslations para cargar los archivos 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.

Archivos de traducción manual (migración)

Para migrar desde otras bibliotecas de i18n o gestionar traducciones manualmente, 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 el 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 al migrar 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_BUILD...>"
  }
}

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

Las dictionaries y los componentes <T> pueden funcionar juntos:

function MixedApproach() {
  const d = useTranslations();
  
  return (
    <div>
      {/* Diccionario para strings simples */}
      <h1>{d('page.title')}</h1>
      
      {/* Componente T para JSX complejo */}
      <T>
        <p>Este es un <strong>mensaje complejo</strong> con <a href="/link">enlaces</a>.</p>
      </T>
      
      {/* Diccionario para etiquetas de formulario */}
      <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 componentes <T> para proyectos nuevos. Los diccionarios se admiten principalmente para la migración y la compatibilidad con flujos de trabajo de traducción existentes.

Traducción con diccionario vs. con 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>;
}

Compromisos

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 de migrar traducciones existentes

Desventajas del diccionario

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

Comienzo rápido

Paso 1: Crear diccionario

Crea un archivo diccionario en la raíz de tu 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 usa 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 dictionary en la raíz del proyecto o en el directorio src.

Paso 2: Uso en componentes

El hook useTranslations te permite acceder a entradas del diccionario:

Componentes del 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

Añade 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

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

dictionary.ts

const dictionary = {
  dashboard: {
    header: {
      welcome: '¡Bienvenido de nuevo!',
      lastLogin: 'Último acceso: {date}'
    },
    stats: {
      totalUsers: 'Total de usuarios: {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: 'Today' })}</p> {/* -> dashboard.header.lastLogin */}
    </header>
  );
}

function DashboardStats() {
  // 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ían usar loadTranslations para generar automáticamente traducciones a partir de su diccionario base:

dictionary.ts

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

export default dictionary;

Crea una función loadTranslations para cargar los archivos 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.

Archivos de traducción manual (migración)

Para migrar desde otras bibliotecas de i18n o gestionar traducciones manualmente, 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 el 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 al migrar 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_BUILD...>"
  }
}

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

Las dictionaries y los componentes <T> pueden funcionar juntos:

function MixedApproach() {
  const d = useTranslations();
  
  return (
    <div>
      {/* Diccionario para strings simples */}
      <h1>{d('page.title')}</h1>
      
      {/* Componente T para JSX complejo */}
      <T>
        <p>Este es un <strong>mensaje complejo</strong> con <a href="/link">enlaces</a>.</p>
      </T>
      
      {/* Diccionario para etiquetas de formulario */}
      <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 componentes <T> para proyectos nuevos. Los diccionarios se admiten principalmente para la migración y la compatibilidad con flujos de trabajo de traducción existentes.

Traducción con diccionario vs. con 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>;
}

Compromisos

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 de migrar traducciones existentes

Desventajas del diccionario

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

Comienzo rápido

Paso 1: Crear diccionario

Crea un archivo diccionario en la raíz de tu 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 usa 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 dictionary en la raíz del proyecto o en el directorio src.

Paso 2: Uso en componentes

El hook useTranslations te permite acceder a entradas del diccionario:

Componentes del 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

Añade 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

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

dictionary.ts

const dictionary = {
  dashboard: {
    header: {
      welcome: '¡Bienvenido de nuevo!',
      lastLogin: 'Último acceso: {date}'
    },
    stats: {
      totalUsers: 'Total de usuarios: {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: 'Today' })}</p> {/* -> dashboard.header.lastLogin */}
    </header>
  );
}

function DashboardStats() {
  // 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ían usar loadTranslations para generar automáticamente traducciones a partir de su diccionario base:

dictionary.ts

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

export default dictionary;

Crea una función loadTranslations para cargar los archivos 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.

Archivos de traducción manual (migración)

Para migrar desde otras bibliotecas de i18n o gestionar traducciones manualmente, 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 el 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 al migrar 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_BUILD...>"
  }
}

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

Las dictionaries y los componentes <T> pueden funcionar juntos:

function MixedApproach() {
  const d = useTranslations();
  
  return (
    <div>
      {/* Diccionario para strings simples */}
      <h1>{d('page.title')}</h1>
      
      {/* Componente T para JSX complejo */}
      <T>
        <p>Este es un <strong>mensaje complejo</strong> con <a href="/link">enlaces</a>.</p>
      </T>
      
      {/* Diccionario para etiquetas de formulario */}
      <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

GitHubDale una estrella en GitHub

GitHubDale una estrella en GitHub

Dale una estrella en GitHub

Dale una estrella en GitHub