Resumen

gt-i18n ahora admite traducciones basadas en diccionarios mediante getTranslations(). Esto hace que gt-i18n quede alineado con gt-next, gt-react y otras bibliotecas de i18n que usan diccionarios como patrón principal de traducción.

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 de GT (npx gtx translate), detectará automáticamente dictionary.json en la raíz del proyecto y lo traducirá para las configuraciones regionales definidas.

Uso

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

import { getTranslations } from 'gt-i18n';

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:

const t = await getTranslations();

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

• PR #1359
• Referencia de la API getTranslations
• Guía sobre diccionarios