5. Internacionalização
Uma aplicação internacionalizada exibe seus textos no idioma do usuário. O estudo de caso está em francês e inglês. O princípio é simples: as views deixam de conter texto e passam a conter chaves ([MENU.HOME]), e um dicionário para cada idioma associa um texto a cada chave. O idioma selecionado é guardado em um cookie.
5.1. Exemplo 22: uma aplicação bilíngue
| 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. Os dicionários
O arquivo [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."
}
}
|
O arquivo [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."
}
}
|
- Um dicionário é um arquivo JSON organizado por página ou por tema: a chave [HOME.HELLO] designa o texto [HELLO] da seção [HOME];
- Linha 8: um texto pode conter parâmetros, delimitados por chaves, que são substituídos durante a tradução. A ordem das palavras varia de um idioma para outro: por isso um texto não é construído simplesmente concatenando segmentos traduzidos.
5.1.2. O módulo de tradução
O arquivo [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';
// o "locale" usado pelo Intl para datas e números
export const LOCALES: Record<Language, string> = { fr: 'fr-FR', en: 'en-US' };
// um dicionário é um objeto JSON aninhado: { "MENU": { "HOME": "Home" } }
type Dictionary = { [key: string]: string | Dictionary };
// os dicionários são lidos UMA vez, na inicialização
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': descemos até HOME, depois até 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;
}
|
Vamos comentar este código:
- linhas 4–6: os idiomas suportados;
- linha 8: o “locale” de cada idioma, usado por [Intl] para formatar datas e números ([fr-FR]: 23/09/2026, 12,50 €; [en-US]: 9/23/2026, €12.50);
- linhas 14–18: os dicionários são lidos uma única vez, quando o módulo é carregado, e depois mantidos na memória;
- linhas 20–22: uma verificação de tipo como a do [TypeScript] ([value is Language]): após um teste positivo, o compilador sabe que o valor é um [Language];
- linhas 25–28: a tradução. A chave é procurada no dicionário; se não for encontrada, a própria chave é exibida: qualquer omissão fica imediatamente visível na tela. A expressão regular [/\{(\w+)\}/g] encontra cada parâmetro [{name}] e o substitui pelo seu valor;
- linhas 31–40: a chave [HOME.HELLO] é dividida em [HOME] e depois em [HELLO], e o processo continua descendo pelo objeto JSON.
5.1.3. Os helpers
O arquivo [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;
}
// o idioma da página: res.locals.lang, mesclado ao modelo raiz
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'}} ou {{t 'KEY' name=...}}: tradução, com parâmetros nomeados
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);
}
|
- linhas 9–12: o idioma da página está no template raiz ([options.data.root.lang]), onde o middleware [main.ts] o colocou por meio de [res.locals];
- linha 16: o helper [t] traduz uma chave. Os parâmetros nomeados do helper ([options.hash]) são os parâmetros do texto: [{{t 'HOME.HELLO' name=name}}];
- linhas 19–21 e 24–26: datas e valores são formatados de acordo com o idioma.
5.1.4. Seleção do idioma
O arquivo [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());
// o idioma de cada página: o do cookie [language], inglês caso contrário
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();
|
Linhas 22–26: a cada requisição, o idioma é lido do cookie [language] (inglês por padrão) e guardado em [res.locals.lang], e portanto no template de cada view.
O arquivo [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: armazena a escolha em um cookie, depois volta à 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));
}
}
// a página de onde viemos (cabeçalho Referer), da qual mantemos apenas o caminho:
// redirecionar para um endereço completo tirado da requisição permitiria
// enviar o usuário a outro site (vulnerabilidade 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 '/';
}
}
|
- linhas 8–15: [GET /language/en] guarda a seleção em um cookie válido por um ano e depois redireciona para a página de origem do usuário. Um idioma desconhecido resulta em um erro 404;
- linhas 21–32: a página de origem é indicada pelo cabeçalho [Referer], que o navegador acrescenta quando um link é clicado. Mantemos apenas o caminho: redirecionar para uma URL completa vinda da requisição permitiria que um site malicioso criasse um link que, depois de passar pelo nosso site, enviaria o usuário ao site malicioso (uma vulnerabilidade conhecida como [open redirect]).
5.1.5. As views
O arquivo [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>
|
- linha 2: o atributo [lang] da página reflete o idioma selecionado (útil para leitores de tela e corretores ortográficos);
- linha 5: o título da página é uma chave, fornecida pela action ([pageTitle]) e traduzida pela view: [{{t pageTitle}}]. Sem apóstrofos, o argumento do helper é uma variável do template, e não um literal de string.
O arquivo [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>
{{!-- o idioma atual é destacado --}}
<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>
|
Linhas 8–9: dois links (mudar o idioma não modifica nenhum dado da aplicação: um GET é apropriado), com o idioma atual destacado.
O arquivo [views/home.hbs]:
| <h1>{{t 'HOME.TITLE'}}</h1>
<p>{{t 'HOME.HELLO' name=name}}</p>
<p>{{t 'HOME.DATE' date=(longDate today)}}</p>
|
Linha 3: uma subexpressão: a data é primeiro formatada por [longDate] e depois passada como parâmetro [date] ao helper [t].
O arquivo [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 do laço, o helper encontra o idioma no modelo RAIZ --}}
<tr><td>{{name}}</td><td class="text-end">{{money price}}</td></tr>
{{/each}}
</tbody>
</table>
<p>{{t 'PRODUCTS.COUNT' n=count}}</p>
|
O arquivo [src/pages.controller.ts]:
| import { Controller, Get, Render } from '@nestjs/common';
@Controller()
export class PagesController {
@Get()
@Render('home')
home(): object {
// pageTitle é uma CHAVE: a view a traduz
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. Execução
Em francês (após clicar em FR; sem cookie, a página está em inglês, o idioma padrão):


Clique em 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
|
O servidor define o cookie e redireciona para a página de origem, que agora está em inglês:


O estudo de caso funciona exatamente assim, com dicionários mais completos ([i18n/fr.json] e [i18n/en.json]): o mesmo helper [t], o mesmo controller [/language/:language], o mesmo cookie. Há apenas uma diferença: as mensagens de erro geradas pelas camadas de negócio e web também são chaves, traduzidas no último momento pela view.