Blog da 18ways
Como adicionar i18n multilíngue e localização a um app Next.js existente sem prejudicar o SEO nem refazer tudo do zero.
I18n (internacionalização), l10n (localização), suporte multilíngue… como quer que você chame isso, em algum momento você precisa atualizar seu app Next.js para oferecer suporte a mais de um idioma.
A dificuldade não é traduzir uma frase. É adicionar vários idiomas a um app Next.js real sem quebrar o SEO, embaralhar sua base de código ou criar um problema de manutenção para você.
Se você quiser ir direto ao código, confira os exemplos do GitHub do 18ways-next.
Antes de qualquer outra coisa, precisamos instalar nossos pacotes. Vamos configurar as bibliotecas do 18ways, mas ferramentas como i18next funcionam bem se o seu projeto for simples e tiver apenas conteúdo estático.
npm install @18ways/next @18ways/reactCrie seu arquivo de configuração:
// 18ways.config.js
module.exports = {
apiKey: 'pk_dummy_demo_token',
baseLocale: 'en-GB',
router: 'app', // 'app', or 'path' depending on which Next.js router you are using
};Envolva sua configuração do Next.js:
// next.config.js
const { withWays } = require('@18ways/next/config');
const nextConfig = {
/*
* your normal Next.js config here
*/
};
module.exports = withWays(nextConfig);Adicione um proxy raiz para que / possa redirecionar para a localidade correta:
// proxy.js
export { default, config } from '@18ways/next/proxy';Depois, adicione um layout localizado:
// app/layout.jsx
import './styles.css';
import { WaysRoot } from '@18ways/next/server';
export default function RootLayout({ children }) {
return (
<html lang="en">
<body className="next-demo-body">
<WaysRoot>{children}</WaysRoot>
</body>
</html>
);
}E pronto! Agora você tem:
Agora você pode traduzir sua primeira página. Ferramentas como i18next exigirão que você separe todo o seu texto em chaves de tradução e, então, faça referência a elas no seu código. O jeito exato disso vai depender da biblioteca que você escolheu.
Se você estiver usando 18ways, pode simplesmente envolver o texto que deseja traduzir em um componente <T>:
// src/components/MyExampleComponent.jsx
import { useT, T } from '@18ways/react';
export default function MyExampleComponent() {
const t = useT();
return (
<div>
<T>Hello world!</T>
<img
src="https://example.com/image.png"
alt={t('Example image')}
/>
</div>
);
}Você provavelmente quer permitir que os usuários alterem a escolha de idioma deles:
// src/components/Footer.jsx
import { T, LanguageSwitcher } from '@18ways/react';
export default function Footer() {
return (
<footer>
<T>My footer content</T>
<LanguageSwitcher />
</footer>
);
}Depois que a tubulação está instalada, há algumas maneiras pelas quais esses projetos costumam dar errado.
A renderização no servidor (SSR) é o que permite que seu app Next.js renderize o HTML previamente no servidor. Isso é vital tanto para SEO quanto para que o usuário não veja flashes de conteúdo ruim ou idioma incorreto.
Se você estiver usando uma biblioteca como i18next, precisa ter muito cuidado para garantir que suas traduções estejam sendo carregadas e preenchidas durante a renderização no lado do servidor. Você pode testar isso verificando o view-source: da sua página, por exemplo view-source:http://localhost:3000/. Você também deve verificar isso em produção, para garantir que funcione na sua build de produção.
Se você estiver usando 18ways, não se preocupe com isso. Tudo é tratado para você.
Se você estiver usando 18ways, você não precisa se preocupar com isso de forma alguma. O 18ways não precisa de chaves de tradução; você pode deixar seu texto no lugar, como de costume.
Muitos sistemas de i18n exigem que você divida seu código em chaves de tradução. É importante ter cuidado com a forma como você nomeia essas chaves.
Chaves ruins são vagas:
// bad-keys.en-GB.js
module.exports = {
title: 'Continue',
button: 'Pay now',
label: 'Home',
};Essas chaves dizem quase nada a tradutores e desenvolvedores sobre onde o texto aparece.
Melhores chaves incluem contexto:
// better-keys.en-GB.js
module.exports = {
'checkout.payment.primaryButton': 'Pay now',
'checkout.payment.stepTitle': 'Complete your payment',
'account.sidebar.homeLink': 'Home',
};Além disso, evite gerar chaves dinamicamente:
// bad-dynamic-keys.js
const key = `checkout.${status}.${buttonType}`;
const translatedText = t(key);Isso vai quebrar ferramentas da IDE que tentam tornar as chaves de tradução menos insuportáveis. Também vai tornar extremamente difícil buscar e limpar chaves de tradução antigas.
// better-dynamic-keys.js
const keyMap = {
success: {
primary: t('checkout.success.primary'),
default: t('checkout.success.default'),
},
error: {
primary: t('checkout.error.primary'),
default: t('checkout.error.default'),
},
};
const translatedText = keyMap[status][buttonType];Isso é menos DRY, mas é a melhor forma de evitar que as chaves de tradução fiquem inadministráveis.
Ainda melhor é usar uma ferramenta como 18ways; assim, você nunca precisa de chaves de tradução:
// app/[lang]/checkout/page.jsx
<T>Pay now</T>A detecção de localidade significa decidir qual idioma um usuário deve ver antes de ele alternar explicitamente.
Isso normalmente envolve alguma combinação de:
Accept-Language do navegadorNo middleware do Next.js, isso muitas vezes fica assim:
// middleware.js
/**
* You don't need any of this if you're using 18ways
*/
import { NextResponse } from 'next/server';
const acceptedLocales = ['en-GB', 'fr-FR'];
export function middleware(request) {
const savedLocale =
request.cookies.get('preferred-locale')?.value;
const browserLocale =
request.headers
.get('accept-language')
?.split(',')[0] || 'en-GB';
const locale = acceptedLocales.includes(savedLocale)
? savedLocale
: acceptedLocales.includes(browserLocale)
? browserLocale
: 'en-GB';
if (request.nextUrl.pathname === '/') {
return NextResponse.redirect(
new URL(`/${locale}`, request.url)
);
}
return NextResponse.next();
}Algumas bibliotecas têm auxiliares para facilitar isso, em maior ou menor grau. Com o 18ways, a detecção inicial e a camada de redirecionamento são tratadas para você.
Locais diferentes formatam datas, números e dinheiro de maneiras diferentes.
Por exemplo:
04/05/2026 pode significar 4 de maio ou 5 de abril€1.999,00 e 1.999,00 € são ambos válidos, dependendo do idioma/regiãoEm JavaScript puro, você lida com isso sozinho com Intl:
// formatting-dates-and-currency.js
const myLocale = getCurrentLocale(); // depends on your lib
const someTimestamp = new Date('2026-04-13T09:00:00Z');
const dateLabel = new Intl.DateTimeFormat('fr-FR', {
dateStyle: 'long',
}).format(someTimestamp);
const someMoney = {
amount: 1999,
currency: 'EUR',
};
const moneyLabel = new Intl.NumberFormat('de-DE', {
style: 'currency',
currency: someMoney.currency,
}).format(someMoney.amount);
const translatedText = t(
'my.translation.key',
{ dateLabel, moneyLabel }
);Se você estiver usando 18ways, isso é tratado para você:
const someTimestamp = new Date('2026-04-13T09:00:00Z');
const someMoney = {
amount: 1999,
currency: 'EUR',
};
<T>My text with {{ someTimestamp }} and {{ someMoney }}</T>Não construa UI traduzida juntando fragmentos:
// bad-string-joining.jsx
const clickHereText = t('click.here');
const toGetStartedText = t('to.get.started')
<p><a href="#">{clickHereText}</a> {toGetStartedText}.</p>Isso vai quebrar em vários idiomas.
Você pode dizer “👉👉Clique aqui👈👈 para começar” em inglês, mas em francês é mais natural dizer “Para começar, 👉👉clique aqui👈👈”. Alguns idiomas, como o japonês, vão até precisar de palavras antes e depois, como “始めるには👉👉こちら👈👈をクリックしてください”.
A estrutura da frase pode mudar, então dividi-la em partes torna uma boa tradução muito mais difícil.
Frases inteiras são traduzidas melhor porque os tradutores podem reorganizar as palavras naturalmente e ver o significado como uma unidade completa.
Se você estiver traduzindo JSX assim:
// rich-text-message.jsx
<p>
Something <strong>that we want to be bold</strong>
</p>você terá que consultar sua biblioteca de i18n sobre como gerenciar isso, já que isso é tratado de maneiras muito diferentes por bibliotecas diferentes.
Se você estiver usando 18ways, você pode simplesmente traduzir o bloco JSX inteiro como de costume.
// rich-text-message.jsx
<p>
<T>Something <strong>that we want to be bold</strong></T>
</p>Variáveis permitem que você mantenha a frase completa enquanto ainda insere valores em tempo de execução.
A maioria das bibliotecas de i18n oferece suporte a isso de alguma forma. Com o 18ways:
// app/[lang]/page.jsx
<T>Hello {{ name: 'Ada' }}</T>Esse padrão funciona bem para:
A frase continua legível, e o valor continua explícito.
Se você precisar que a própria variável também seja traduzida, certifique-se de envolvê-la em um t(...):
const animal = t('dog');
<T>Favourite animal: {{ animal }}</T>As regras de plural variam de acordo com o idioma. O inglês tem uma forma de plural (1 year, 2 years, etc.). O polonês tem várias formas de plural (1 rok, 2 lata, 5 lat). O japonês não tem forma de plural alguma (1 年, 2 年, 3 年).
A maioria das bibliotecas de i18n permite que você especifique uma sintaxe parecida com ICU para lidar com plurais:
// app/[lang]/page.jsx
<T>
{{
unreadCount,
format:
'plural, =0{No unread messages} =1{One unread message} other{{unreadCount} unread messages}',
}}
</T>O acima funcionará de 18 maneiras, mas você também pode simplesmente fazer isso na maioria dos casos:
// app/[lang]/page.jsx
<T>{{ unreadCount }} unread messages</T>18ways vai lidar com os plurais para você!
Adicionar vários idiomas a um app Next.js não precisa virar um projeto de reescrita.
Se você não estiver usando uma solução como a 18ways — certifique-se de acertar o roteamento e o SSR, depois trabalhe na migração do seu texto para chaves de tradução, tomando cuidado para evitar as armadilhas comuns de i18n.
Se você estiver usando 18ways, então isso tudo é tratado para você, e você só precisa começar a envolver seu texto em blocos <T>!