5. Internacionalización
Una aplicación internacionalizada muestra su texto en el idioma del usuario. El caso de estudio está en francés e inglés. El principio es simple: las vistas ya no contienen texto, sino claves ([MENU.HOME]), y un diccionario por cada idioma asocia un texto a cada clave. El idioma seleccionado se guarda en una cookie.
5.1. Ejemplo 22: una aplicación bilingüe
| 22-i18n/
├── i18n/
│ ├── en.json
│ └── fr.json
├── src/
│ ├── app.module.ts
│ ├── helpers.ts
│ ├── i18n.ts
│ ├── language.controller.ts
│ ├── main.ts
│ └── pages.controller.ts
├── views/
│ ├── partials/
│ │ └── navbar.hbs
│ ├── home.hbs
│ ├── layout.hbs
│ └── products.hbs
├── nest-cli.json
└── tsconfig.json
|
5.1.1. Los diccionarios
El archivo [i18n/fr.json]:
| {
"MENU": {
"HOME": "Accueil",
"PRODUCTS": "Produits"
},
"HOME": {
"TITLE": "Bienvenue",
"HELLO": "Bonjour {name} !",
"DATE": "Nous sommes le {date}."
},
"PRODUCTS": {
"TITLE": "Nos produits",
"NAME": "Produit",
"PRICE": "Prix",
"COUNT": "{n} produit(s) au catalogue."
}
}
|
El archivo [i18n/en.json]:
| {
"MENU": {
"HOME": "Home",
"PRODUCTS": "Products"
},
"HOME": {
"TITLE": "Welcome",
"HELLO": "Hello {name}!",
"DATE": "Today is {date}."
},
"PRODUCTS": {
"TITLE": "Our products",
"NAME": "Product",
"PRICE": "Price",
"COUNT": "{n} product(s) in the catalogue."
}
}
|
- Un diccionario es un archivo JSON, organizado por página o por tema: la clave [HOME.HELLO] se refiere al texto [HELLO] de la sección [HOME];
- Línea 8: un texto puede contener parámetros, entre llaves, que se reemplazan durante la traducción. El orden de las palabras varía de un idioma a otro: por eso un texto no se crea simplemente concatenando segmentos traducidos.
5.1.2. El módulo de traducción
El archivo [src/i18n.ts]:
| import { readFileSync } from 'fs';
import { join } from 'path';
export type Language = 'fr' | 'en';
export const LANGUAGES: Language[] = ['fr', 'en'];
export const DEFAULT_LANGUAGE: Language = 'en';
// la "locale" que usa Intl para las fechas y los números
export const LOCALES: Record<Language, string> = { fr: 'fr-FR', en: 'en-US' };
// un diccionario es un objeto JSON anidado: { "MENU": { "HOME": "Home" } }
type Dictionary = { [key: string]: string | Dictionary };
// los diccionarios se leen UNA SOLA VEZ, al inicio
const FOLDER = join(__dirname, '..', 'i18n');
const dictionaries: Record<Language, Dictionary> = {
fr: JSON.parse(readFileSync(join(FOLDER, 'fr.json'), 'utf-8')),
en: JSON.parse(readFileSync(join(FOLDER, 'en.json'), 'utf-8')),
};
export function isLanguage(value: unknown): value is Language {
return typeof value === 'string' && (LANGUAGES as string[]).includes(value);
}
// translate('en', 'HOME.HELLO', { name: 'Marie' }) -> "Hello Marie!"
export function translate(language: Language, key: string, params: Record<string, unknown> = {}): string {
const text = lookup(dictionaries[language], key) ?? key;
return text.replace(/\{(\w+)\}/g, (whole, name: string) => (name in params ? String(params[name]) : whole));
}
// 'HOME.HELLO': descendemos a HOME y luego a HELLO
function lookup(dictionary: Dictionary, key: string): string | null {
let node: string | Dictionary | undefined = dictionary;
for (const part of key.split('.')) {
if (typeof node !== 'object') {
return null;
}
node = node[part];
}
return typeof node === 'string' ? node : null;
}
|
Comentemos este código:
- líneas 4–6: los idiomas admitidos;
- línea 8: la «configuración regional» (locale) de cada idioma, que [Intl] utiliza para dar formato a fechas y números ([fr-FR]: 23/09/2026, 12,50 €; [en-US]: 9/23/2026, €12.50);
- líneas 14–18: los diccionarios se leen una sola vez, cuando se carga el módulo, y luego se mantienen en memoria;
- líneas 20–22: una verificación de tipo como la de [TypeScript] ([value is Language]): tras una prueba positiva, el compilador sabe que el valor es un [Language];
- líneas 25–28: la traducción. La clave se busca en el diccionario; si no se encuentra, se muestra la propia clave: cualquier omisión es inmediatamente visible en la pantalla. La expresión regular [/\{(\w+)\}/g] encuentra cada parámetro [{name}] y lo reemplaza por su valor;
- líneas 31–40: la clave [HOME.HELLO] se divide en [HOME] y luego en [HELLO], y el proceso continúa descendiendo por el objeto JSON.
5.1.3. Los helpers
El archivo [src/helpers.ts]:
| import { HelperOptions } from 'handlebars';
import { Language, DEFAULT_LANGUAGE, LOCALES, isLanguage, translate } from './i18n';
interface Hbs {
registerHelper(name: string, fn: (...args: any[]) => unknown): void;
}
// el idioma de la página: res.locals.lang, fusionado en el modelo raíz
function languageOf(options: HelperOptions): Language {
const lang = options.data?.root?.lang;
return isLanguage(lang) ? lang : DEFAULT_LANGUAGE;
}
export function registerHelpers(hbs: Hbs): void {
// {{t 'KEY'}} o {{t 'KEY' name=...}}: traducción, con parámetros con nombre
hbs.registerHelper('t', (key: string, options: HelperOptions) => translate(languageOf(options), key, options.hash));
// {{longDate when}}: "mercredi 23 septembre 2026" / "Wednesday, September 23, 2026"
hbs.registerHelper('longDate', (when: string, options: HelperOptions) =>
new Intl.DateTimeFormat(LOCALES[languageOf(options)], { dateStyle: 'full' }).format(new Date(when)),
);
// {{money price}}: "12,50 €" / "€12.50"
hbs.registerHelper('money', (amount: number, options: HelperOptions) =>
new Intl.NumberFormat(LOCALES[languageOf(options)], { style: 'currency', currency: 'EUR' }).format(amount),
);
hbs.registerHelper('eq', (a: unknown, b: unknown) => a === b);
}
|
- líneas 9–12: el idioma de la página está en la plantilla raíz ([options.data.root.lang]), donde lo colocó el middleware [main.ts] mediante [res.locals];
- línea 16: el helper [t] traduce una clave. Los parámetros con nombre del helper ([options.hash]) son los parámetros del texto: [{{t 'HOME.HELLO' name=name}}];
- líneas 19–21 y 24–26: las fechas y los importes se formatean según el idioma.
5.1.4. Selección del idioma
El archivo [src/main.ts]:
| import { NestFactory } from '@nestjs/core';
import { NestExpressApplication } from '@nestjs/platform-express';
import * as cookieParser from 'cookie-parser';
import { NextFunction, Request, Response } from 'express';
import * as hbs from 'hbs';
import { dirname, join } from 'path';
import { AppModule } from './app.module';
import { registerHelpers } from './helpers';
import { isLanguage, DEFAULT_LANGUAGE } from './i18n';
const ROOT = join(__dirname, '..');
async function bootstrap() {
const app = await NestFactory.create<NestExpressApplication>(AppModule);
app.useStaticAssets(join(dirname(require.resolve('bootstrap/package.json')), 'dist'), { prefix: '/bootstrap/' });
app.setBaseViewsDir(join(ROOT, 'views'));
app.setViewEngine('hbs');
registerHelpers(hbs);
await new Promise<void>((done) => hbs.registerPartials(join(ROOT, 'views', 'partials'), () => done()));
app.use(cookieParser());
// el idioma de cada página: el de la cookie [language], inglés en caso contrario
app.use((req: Request, res: Response, next: NextFunction) => {
const cookie = req.cookies?.language;
res.locals.lang = isLanguage(cookie) ? cookie : DEFAULT_LANGUAGE;
next();
});
await app.listen(3000);
console.log('Server started on http://localhost:3000');
}
bootstrap();
|
Líneas 22–26: en cada solicitud, el idioma se lee de la cookie [language] (inglés por defecto) y se guarda en [res.locals.lang], y por lo tanto en la plantilla de cada vista.
El archivo [src/language.controller.ts]:
| import { Controller, Get, NotFoundException, Param, Req, Res } from '@nestjs/common';
import { Request, Response } from 'express';
import { isLanguage } from './i18n';
@Controller('language')
export class LanguageController {
// GET /language/fr: almacena la elección en una cookie y luego regresa a la página anterior
@Get(':language')
change(@Param('language') language: string, @Req() req: Request, @Res() res: Response): void {
if (!isLanguage(language)) {
throw new NotFoundException();
}
res.cookie('language', language, { maxAge: 365 * 24 * 3600 * 1000, sameSite: 'lax', httpOnly: true });
res.redirect(originPage(req));
}
}
// la página de la que venimos (encabezado Referer), de la cual conservamos solo la ruta:
// redirigir a una dirección completa tomada de la solicitud permitiría
// enviar al usuario a otro sitio (vulnerabilidad de "open redirect")
function originPage(req: Request): string {
const referer = req.get('referer');
if (!referer) {
return '/';
}
try {
const url = new URL(referer);
return url.pathname + url.search;
} catch {
return '/';
}
}
|
- líneas 8–15: [GET /language/en] guarda la selección en una cookie válida por un año y luego redirige a la página de la que venía el usuario. Un idioma desconocido produce un error 404;
- líneas 21–32: la página de origen se indica en el encabezado [Referer], que el navegador agrega cuando se hace clic en un enlace. Solo conservamos la ruta: redirigir a una URL completa tomada de la solicitud permitiría que un sitio malicioso cree un enlace que, tras pasar por nuestro sitio, envíe al usuario al sitio malicioso (una vulnerabilidad conocida como [open redirect]).
5.1.5. Las vistas
El archivo [views/layout.hbs]:
| <!doctype html>
<html lang="{{lang}}">
<head>
<meta charset="utf-8">
<title>{{t pageTitle}}</title>
<link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
</head>
<body>
<div class="container py-3">
{{> navbar}}
{{{body}}}
</div>
</body>
</html>
|
- línea 2: el atributo [lang] de la página refleja el idioma seleccionado (útil para los lectores de pantalla y los correctores ortográficos);
- línea 5: el título de la página es una clave, proporcionada por la acción ([pageTitle]) y traducida por la vista: [{{t pageTitle}}]. Sin apóstrofos, el argumento del helper es una variable de la plantilla, no una cadena literal.
El archivo [views/partials/navbar.hbs]:
| <nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
<div class="navbar-nav me-auto">
<a class="nav-link" href="/">{{t 'MENU.HOME'}}</a>
<a class="nav-link" href="/products">{{t 'MENU.PRODUCTS'}}</a>
</div>
{{!-- el idioma actual aparece resaltado --}}
<div class="btn-group btn-group-sm">
<a class="btn {{#if (eq lang 'fr')}}btn-primary{{else}}btn-outline-primary{{/if}}" href="/language/fr">FR</a>
<a class="btn {{#if (eq lang 'en')}}btn-primary{{else}}btn-outline-primary{{/if}}" href="/language/en">EN</a>
</div>
</nav>
|
Líneas 8–9: dos enlaces (cambiar el idioma no modifica ningún dato de la aplicación: un GET es adecuado), con el idioma actual resaltado.
El archivo [views/home.hbs]:
| <h1>{{t 'HOME.TITLE'}}</h1>
<p>{{t 'HOME.HELLO' name=name}}</p>
<p>{{t 'HOME.DATE' date=(longDate today)}}</p>
|
Línea 3: una subexpresión: la fecha primero recibe formato de [longDate] y luego se pasa como parámetro [date] al helper [t].
El archivo [views/products.hbs]:
| <h1>{{t 'PRODUCTS.TITLE'}}</h1>
<table class="table table-sm w-auto">
<thead><tr><th>{{t 'PRODUCTS.NAME'}}</th><th class="text-end">{{t 'PRODUCTS.PRICE'}}</th></tr></thead>
<tbody>
{{#each products}}
{{!-- dentro del bucle, el helper encuentra el idioma en el modelo RAÍZ --}}
<tr><td>{{name}}</td><td class="text-end">{{money price}}</td></tr>
{{/each}}
</tbody>
</table>
<p>{{t 'PRODUCTS.COUNT' n=count}}</p>
|
El archivo [src/pages.controller.ts]:
| import { Controller, Get, Render } from '@nestjs/common';
@Controller()
export class PagesController {
@Get()
@Render('home')
home(): object {
// pageTitle es una CLAVE: la vista la traduce
return { pageTitle: 'HOME.TITLE', name: 'Marie', today: '2026-09-23' };
}
@Get('products')
@Render('products')
products(): object {
const products = [
{ name: 'Keyboard', price: 25 },
{ name: 'Mouse', price: 12.5 },
{ name: 'Screen', price: 1149 },
];
return { pageTitle: 'PRODUCTS.TITLE', products, count: products.length };
}
}
|
5.1.6. Ejecución
En francés (después de hacer clic en FR; sin cookie, la página está en inglés, el idioma predeterminado):


Clic en EN:
| curl -i -H "Referer: http://localhost:3000/products" http://localhost:3000/language/en
|
| HTTP/1.1 302 Found
Set-Cookie: language=en; Max-Age=31536000; Path=/; Expires=Thu, 23 Sep 2027 14:16:03 GMT; HttpOnly; SameSite=Lax
Location: /products
Content-Type: text/plain; charset=utf-8
Content-Length: 31
Found. Redirecting to /products
|
El servidor establece la cookie y redirige a la página de origen, que ahora aparece en inglés:


El caso de estudio procede exactamente de este modo, con diccionarios más completos ([i18n/fr.json] y [i18n/en.json]): el mismo helper [t], el mismo controlador [/language/:language], la misma cookie. Solo hay una diferencia: los mensajes de error generados por las capas de negocio y web también son claves, traducidas en el último momento por la vista.