Atrás
gt-i18ngt-nodedictionariesgetTranslationsi18n
BlogRegistro de cambios

gt-i18n 0.9.0: Traducciones basadas en diccionarios

Ernest McCarter

Resumen

gt-i18n ahora ofrece traducciones basadas en diccionarios para las integraciones con frameworks. En aplicaciones de Node.js, usa la exportación pública getTranslations() de gt-node; gt-i18n@0.9.0 no la exporta desde la raíz de su paquete.

PaqueteVersión
gt-i18n0.9.0
gt-node0.7.0

Configuración

Crea un archivo dictionary.json en la raíz de tu proyecto con tus cadenas de origen (en inglés):

{
  "greeting": {
    "hello": "Hello!"
  },
  "user": {
    "welcome": "Welcome, {name}!"
  },
  "errors": {
    "notFound": "Page not found",
    "unauthorized": "Access denied"
  }
}

Al ejecutar la CLI (npx gt translate), detecta dictionary.json en la raíz del proyecto y lo traduce para las configuraciones regionales definidas.

Configura el entorno de ejecución de Node.js con initializeGT:

import { initializeGT } from 'gt-node';
import dictionary from './dictionary.json';

initializeGT({
  defaultLocale: 'en',
  locales: ['en', 'es'],
  dictionary,
});

Uso

Dado el diccionario de origen anterior, llama a getTranslations() para obtener una función t que recupera entradas de tu diccionario:

import { getTranslations, withGT } from 'gt-node';

await withGT('en', async () => {
  const t = await getTranslations();

  t('greeting.hello'); // "¡Hola!"
  t('user.welcome', { name: 'Alice' }); // "¡Bienvenida, Alice!"
});

Subdiccionarios con t.obj()

t() devuelve una sola cadena. t.obj() devuelve un subárbol completo del diccionario como un objeto:

// Dentro del callback de withGT anterior:
t('errors.notFound'); // "Página no encontrada"

const errors = t.obj('errors');
// { notFound: "Página no encontrada", unauthorized: "Acceso denegado" }

Cuando a un diccionario traducido le faltan claves, las entradas que faltan se completan con las del diccionario de origen. Esto significa que las traducciones parciales no provocarán errores en tiempo de ejecución — las claves sin traducir usan el texto de origen.

Comportamiento de búsqueda

Hay dos reglas que determinan cómo se resuelven las búsquedas:

  1. Falta una traducción → contenido alternativo de la configuración regional predeterminada. Si una clave existe en el diccionario de origen pero no tiene traducción para la configuración regional actual, t() devuelve el texto de origen.
  2. Falta una entrada de origen → error. Si una clave no existe en absoluto en el diccionario de origen, t() lanza un error. Esto es intencional: si una clave no está definida en el diccionario de origen, es un error, no una traducción faltante. Este comportamiento se aplicará en todas las bibliotecas de GT en una próxima refactorización.

La segunda regla supone que los diccionarios traducidos coinciden con la estructura de tu diccionario de origen, que es como GT genera traducciones automáticamente.

Enlaces