Next.js

O pacote translate-projects-nextjs tem duas partes: um comando que traduz seus arquivos JSON e utilitários para usá-los no Next.js (App Router): middleware de idioma, provider do i18next, Link e hooks com preenchimento automático.

Requisitos

• Node.js 20 ou superior.
• Next.js 14 ou superior e React 18 ou superior. São dependências peer: o pacote usa as do seu projeto.
• Um projeto e um API token do Translate Projects. Veja Primeiros passos.

1. Instale o pacote

Terminal

npm i translate-projects-nextjs

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

2. Escreva seus textos

Coloque os textos do idioma base em src/locales/<idioma base>/. Cada arquivo JSON (também em subpastas) é um namespace do i18next e o aninhamento é mantido:

src/locales/es/translation.json

{
  "home": {
    "title": "Bienvenido"
  }
}

3. Configure a tradução

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

translate.config.mjs

export default {
  sourceLang: 'es', // Idioma base: o idioma padrão do projeto
  targetLangs: ['en', 'pt-BR', 'fr'], // Idiomas a gerar
  apiKey: process.env.TRANSLATE_PROJECTS_API_KEY,
  // outputDir: './src/locales', // Valor padrão
  // scanner: true, // Opcional: extrai t('...') e <Trans> de ./src
};

Adicione o script em package.json:

package.json

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

4. Traduza

Terminal

export TRANSLATE_PROJECTS_API_KEY=tu_token
npm run translate

O comando não lê arquivos .env sozinho: exporte a variável no terminal ou no CI, ou carregue-a você mesmo, por exemplo com node --env-file=.env.local node_modules/.bin/translate-projects-nextjs translate. Ele termina com código 0 se todos os idiomas foram traduzidos e com 1 em caso de qualquer erro.

Arquivos que são gerados

src/locales/
├── es/translation.json   ← seu idioma base
├── en/translation.json   ← gerado
├── pt-BR/translation.json
└── fr/translation.json

Faça commit dos arquivos gerados: o app os importa na compilação. Não os edite manualmente, eles são sobrescritos na próxima execução. Com o scanner ativado, <idioma base>/translation.json também é sobrescrito com os textos encontrados no código.

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

Middleware

Redireciona para /<idioma>/... e salva o idioma no cookie NEXT_LOCALE. As rotas /_next, /api, /locales e /favicon.ico são sempre ignoradas.

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', 'pt-BR', 'fr'],
    ignorePaths: ['/images'], // Opcional
  });
}

Provider

app/[locale]/layout.tsx

import { TranslationsProvider } from 'translate-projects-nextjs/provider';
import es from '@/locales/es/translation.json';
import en from '@/locales/en/translation.json';

export default async function Layout({
  children,
  params,
}: {
  children: React.ReactNode;
  params: Promise<{ locale: string }>;
}) {
  const { locale } = await params;

  return (
    <html lang={locale}>
      <body>
        <TranslationsProvider
          lng={locale as any}
          initialLocale={locale as any}
          i18nConfig={{
            fallbackLng: ['es'],
            supportedLngs: ['es', 'en'],
            resources: {
              es: { translation: es },
              en: { translation: en },
            },
          }}
        >
          {children}
        </TranslationsProvider>
      </body>
    </html>
  );
}

Textos com preenchimento automático

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('home.title')}</h1>; // As chaves são preenchidas automaticamente
}

useTranslation e <Trans> de react-i18next também funcionam.

Navegação

app/[locale]/nav.tsx

'use client';
import { Link } from 'translate-projects-nextjs/link';
import { useLocalizedRouter } from 'translate-projects-nextjs/hooks';

export function Nav() {
  const router = useLocalizedRouter();
  return (
    <>
      <Link href="/about">About</Link> {/* -> /<locale>/about */}
      <button onClick={() => router.push('/', undefined, 'en')}>English</button>
    </>
  );
}

Cache e forçar

Arquivos sem alterações não são enviados nem traduzidos novamente: uma execução sem alterações faz uma única requisição. Se você apagar um arquivo gerado, ele é reescrito a partir do cache sem novas requisições. Este pacote não tem --force: para traduzir tudo novamente, apague ~/.config/translate-projects-core/cache.json (afeta todos os projetos da equipe, cada um é sincronizado uma vez) e execute novamente. Mais detalhes em Cache e erros.

Erros comuns

Se a API falhar ou retornar um resultado parcial, as traduções existentes são mantidas, o comando termina com código 1 e os textos que faltam são tentados novamente na próxima execução.

• Token inválido (401): verifique TRANSLATE_PROJECTS_API_KEY.
• Falta a key de IA (MISSING_API_KEY): configure o provedor, o modelo e a key no projeto. Enquanto isso, os textos sem tradução não são gravados no arquivo e o i18next mostra o texto de fallbackLng.
• Missing required configuration fields: apiKey: a variável TRANSLATE_PROJECTS_API_KEY não está definida no terminal onde você executa o comando.
• Não foi encontrado translate.config.mjs: o comando deve ser executado na raiz do projeto.
• Conflito de dependências ao instalar: verifique se seu projeto usa Next.js 14 ou superior e React 18 ou superior.

Grátis

🚀 Automatize suas traduções de graça

Translate Projects é gratuito. Você cria seu projeto, conecta a chave do seu provedor de IA e paga apenas a ele pelo que gastar.

• Sem planos nem cartão de crédito: Todos os recursos estão disponíveis desde o primeiro dia.
• Use sua própria IA: Claude, OpenAI, DeepSeek ou Gemini. Sua chave é armazenada criptografada.
• Rede de traduções compartilhada: Se um texto já foi traduzido, você o recebe instantaneamente sem gastar sua chave.
• Painel de administração: Revise e edite todas as suas traduções em um único lugar.

Criar conta grátis →

Suporte

Estamos aqui para ajudar você

Se você tiver alguma dúvida, precisar de ajuda ou quiser contribuir, não hesite em entrar em contato comigo. Estou à sua disposição para apoiá-lo no que precisar.

• Site: neiderruiz.com
• GitHub: @neiderruiz
• Twitter: @neiderruiz
• YouTube: Neider Ruiz

Apoie o Projeto

Se este projeto foi útil para você, convido você a me pagar um café. Seu apoio me ajuda a continuar melhorando e criando conteúdo de valor. Obrigado por estar aqui! ☕