Typesafe-i18n: Internacionalización con soporte completo de tipos en TypeScript

En el desarrollo web moderno, la internacionalización (i18n) no es solo traducir texto, sino un sistema completo de gestión de localización. Typesafe-i18n es una librería para TypeScript que lleva la internacionalización al siguiente nivel, garantizando total seguridad de tipos en cada etapa: desde la escritura de las traducciones hasta su uso en el código.

¿Por qué necesitas esta librería? Las soluciones tradicionales de i18n (como i18next) a menudo trabajan con cadenas dinámicas, lo que provoca errores: errores tipográficos en las claves, argumentos incorrectos o traducciones faltantes. Typesafe-i18n resuelve este problema de raíz: si escribes LL.WELCOME({name: "Carlos"}), TypeScript verificará si la clave WELCOME existe, si acepta el parámetro name y de qué tipo es ese parámetro. Los errores de localización se convierten en errores de compilación, no en bugs en tiempo de ejecución.

La librería es ideal para proyectos donde la tipificación estricta es crucial: aplicaciones React/Vue/Angular, servidores Node.js, librerías de componentes. Soporta pluralización, interpolación, claves anidadas, carga asíncrona y generación de tipos basada en tus archivos de traducción. En este artículo, analizaremos todos los aspectos del trabajo con Typesafe-i18n: desde la instalación hasta técnicas avanzadas.

Instalación

La instalación se realiza mediante npm (o yarn/pnpm):

npm install typesafe-i18n

Para la generación de tipos y archivos de traducción, necesitarás un paquete adicional:

npm install --save-dev typesafe-i18n-cli

Después de la instalación, inicializa el proyecto:

npx typesafe-i18n --init

Este comando creará la estructura básica de carpetas y archivos de configuración.

Inicio rápido: ejemplo mínimo funcional

Creemos una aplicación simple que salude al usuario en diferentes idiomas.

Paso 1: Crea el archivo de traducción

Crea el archivo src/i18n/en/index.ts:

import type { Translation } from '../i18n-types'

const en: Translation = {
   HI: 'Hello {name}!',
   GOODBYE: 'Goodbye, {name}!'
}

export default en

Paso 2: Crea el archivo de traducción para español

Crea el archivo src/i18n/es/index.ts:

import type { Translation } from '../i18n-types'

const es: Translation = {
   HI: '¡Hola {name}!',
   GOODBYE: '¡Adiós, {name}!'
}

export default es

Paso 3: Ejecuta la generación de tipos

npx typesafe-i18n

Paso 4: Usa en el código

import { i18n } from './i18n/i18n-util'
import { loadLocale } from './i18n/i18n-util.sync'
import { L } from './i18n/i18n-util'

// Cargamos las locales
loadLocale('en')
loadLocale('es')

// Creamos una instancia para inglés
const LL_en = i18n('en')
console.log(LL_en.HI({ name: 'Alex' })) // Output: Hello Alex!

// Cambiamos a español
const LL_es = i18n('es')
console.log(LL_es.HI({ name: 'Carlos' })) // Output: ¡Hola Carlos!

Nota: si intentas llamar a LL_en.HI() sin el argumento name, TypeScript mostrará un error de compilación. Si te equivocas al escribir la clave (LL_en.Hello), también obtendrás un error.

Métodos y funciones principales

Analicemos las 8 funciones y métodos clave de la librería Typesafe-i18n.

1. i18n(locale: Locales): TranslationFunctions

Firma: i18n(locale: Locales): TranslationFunctions

Qué hace: Crea una instancia del traductor para la locale especificada. Devuelve un objeto con todas las funciones de traducción.

import { i18n } from './i18n/i18n-util'

const LL = i18n('es')
console.log(LL.HI({ name: 'María' })) // ¡Hola María!