← Blog

Como traduzir um app Next.js (App Router) para vários idiomas com i18next

Guia passo a passo: traduza seu app Next.js do espanhol para inglês, japonês, português e francês com npm run translate e i18next. Com a saída real.

· 3 min de leitura

Quase todos os projetos Next.js com i18n acabam do mesmo jeito: um translation.json em espanhol e uma tarde copiando para o ChatGPT, colando a resposta e conferindo se nenhuma chave foi alterada. Depois alguém adiciona um texto e tudo recomeça.

Neste guia traduzimos um app Next.js (App Router) do espanhol para inglês, japonês, português e francês com um único comando, npm run translate, usando i18next e o pacote translate-projects-nextjs. Tudo o que você vê abaixo (arquivos e terminal) é a saída real de uma execução.

O que você precisa

  • Node.js 20 ou superior, Next.js 14+ e React 18+.
  • Uma conta gratuita na Translate Projects com um projeto e seu API token (Primeiros passos).
  • A API key do seu provedor de IA: Claude, OpenAI, DeepSeek ou Gemini. Não há planos nem cartão: você paga apenas ao seu provedor pelo que usar.

1. Instale o pacote

npm i translate-projects-nextjs

i18next e react-i18next são instalados com o pacote.

2. Escreva seus textos no idioma base

Cada arquivo JSON dentro de src/locales/<idioma base>/ é um namespace do i18next, e o aninhamento é preservado. Este é o arquivo do app de exemplo:

// src/locales/es/translation.json
{
  "nav": {
    "inicio": "Inicio",
    "precios": "Precios"
  },
  "hero": {
    "titulo": "Organiza tus tareas sin perder el ritmo",
    "subtitulo": "Planifica tu semana, comparte proyectos con tu equipo y recibe recordatorios a tiempo.",
    "boton": "Empieza gratis"
  },
  "login": {
    "email": "Correo electrónico",
    "password": "Contraseña",
    "entrar": "Iniciar sesión",
    "olvido": "¿Olvidaste tu contraseña?"
  }
}

3. Configure os idiomas

Crie translate.config.mjs na raiz do projeto. O token é lido da variável de ambiente TRANSLATE_PROJECTS_API_KEY:

export default {
  sourceLang: 'es',
  targetLangs: ['en', 'ja', 'pt-BR', 'fr'],
  apiKey: process.env.TRANSLATE_PROJECTS_API_KEY,
};

E adicione o script em package.json:

{
  "scripts": {
    "translate": "translate-projects-nextjs translate"
  }
}

4. Traduza

export TRANSLATE_PROJECTS_API_KEY=tu_token
npm run translate

Saída real da execução (sem as marcações de tempo):

✅ Success: Total languages to translate: 4
ℹ️  Info: 🔄 Syncing (9) - src/locales/es/translation.json...
✅ Success: Translation completed: EN 📄 -> 📁 `src/locales/en/translation.json`
✅ Success: Translation completed: JA 📄 -> 📁 `src/locales/ja/translation.json`
✅ Success: Translation completed: PT-BR 📄 -> 📁 `src/locales/pt-BR/translation.json`
✅ Success: Translation completed: FR 📄 -> 📁 `src/locales/fr/translation.json`
✅ Success: Translation completed successfully.

Nove textos para quatro idiomas levaram cerca de 14 segundos. Assim fica o inglês, com as mesmas chaves:

// src/locales/en/translation.json
{
  "nav": {
    "inicio": "Home",
    "precios": "Pricing"
  },
  "hero": {
    "titulo": "Organize your tasks without losing momentum",
    "subtitulo": "Plan your week, share projects with your team and get reminders on time.",
    "boton": "Start for free"
  },
  "login": {
    "email": "Email",
    "password": "Password",
    "entrar": "Sign in",
    "olvido": "Forgot your password?"
  }
}

E o japonês:

// src/locales/ja/translation.json
{
  "nav": {
    "inicio": "ホーム",
    "precios": "料金"
  },
  "hero": {
    "titulo": "ペースを崩さずタスクを整理しよう",
    "subtitulo": "週間計画を立て、チームとプロジェクトを共有し、期限に合わせてリマインダーを受け取れます。",
    "boton": "無料で始める"
  },
  "login": {
    "email": "メールアドレス",
    "password": "パスワード",
    "entrar": "ログイン",
    "olvido": "パスワードをお忘れですか？"
  }
}

O comando não lê o .env sozinho: exporte a variável no terminal ou no CI, ou carregue-a com node --env-file=.env.local node_modules/.bin/translate-projects-nextjs translate.

5. Use as traduções no Next.js

O pacote também traz a parte do app: um middleware que redireciona para /<idioma>/... e salva o cookie NEXT_LOCALE, um provider do i18next, um Link localizado e hooks com autocompletar de chaves.

// middleware.ts
import { NextRequest } from 'next/server';
import { langMiddleware } from 'translate-projects-nextjs/middleware';

export function middleware(request: NextRequest) {
  return langMiddleware({
    request,
    defaultLocale: 'es',
    locales: ['es', 'en', 'ja', 'pt-BR', 'fr'],
  });
}
// app/[locale]/title.tsx
'use client';
import { useTypedTranslation } from 'translate-projects-nextjs/hooks';
import type es from '@/locales/es/translation.json';

export function Title() {
  const { t } = useTypedTranslation<typeof es>();
  return <h1>{t('hero.titulo')}</h1>; // las claves se autocompletan
}

O provider (TranslationsProvider) vai em app/[locale]/layout.tsx; o código completo está no guia do Next.js. useTranslation e <Trans> do react-i18next também funcionam.

Como evita traduzir duas vezes

  • Só são enviados os arquivos que mudaram: uma execução sem alterações faz uma única requisição.
  • Há uma rede compartilhada de traduções: se um texto já foi traduzido antes para esse idioma, ele chega instantaneamente sem gastar sua key de IA.
  • Se você apagar um arquivo gerado, ele é reescrito a partir do cache sem novas requisições.
  • Se a API falhar, as traduções existentes são mantidas, o comando sai com código 1 e o que faltar é tentado novamente na próxima execução.

Erros comuns

  • Token inválido (401): verifique TRANSLATE_PROJECTS_API_KEY.
  • Missing required configuration fields: apiKey: a variável não está definida no terminal onde você executa o comando.
  • Falta a key de IA (MISSING_API_KEY): configure provedor, modelo e key no projeto.
  • Não encontra translate.config.mjs: execute o comando na raiz do projeto.

Também há pacotes para React, Astro, Docusaurus (npm) e Django (PyPI). Crie seu projeto grátis em translateprojects.dev e traduza seu app hoje.