Pular para o conteúdo principal

React

El paquete translate-projects-react traduce los archivos JSON de react-i18next de tu app a varios idiomas y conserva la estructura de claves. Opcionalmente extrae los textos de tu código con un escáner.

Requisitos​

  • Node.js 20 ou superior.
  • Um app React (por exemplo, criado com Vite) com i18next e react-i18next.
  • Um projeto e um API token do Translate Projects. Veja Primeiros passos.

1. Instala los paquetes​

Terminal
npm i i18next react-i18next i18next-http-backend
npm i translate-projects-react

2. Configura i18next​

Crie src/i18n.js. Os arquivos de cada idioma são carregados de public/locales/<lang>/translation.json:

src/i18n.js
import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import HttpBackend from 'i18next-http-backend';

i18n
  .use(HttpBackend)
  .use(initReactI18next)
  .init({
    lng: 'es',
    fallbackLng: 'es',
    ns: ['translation'],
    defaultNS: 'translation',
    interpolation: { escapeValue: false },
    backend: { loadPath: '/locales/{{lng}}/{{ns}}.json' },
  });

export default i18n;

Importe-o uma vez em src/main.jsx:

src/main.jsx
import './i18n';

3. Escreva seus textos​

Coloque os textos do idioma base em public/locales/<idioma base>/translation.json (chaves aninhadas são suportadas):

public/locales/es/translation.json
{
  "home": {
    "title": "Bienvenido",
    "subtitle": "Traduce tu app en minutos"
  }
}

E use-os nos seus componentes:

src/App.jsx
import { useTranslation, Trans } from 'react-i18next';

export default function App() {
  const { t } = useTranslation();
  return (
    <>
      <h1>{t('home.title')}</h1>
      <Trans>Hola, este texto también se traduce</Trans>
    </>
  );
}

Com o scanner ativado (scanner: true), os textos de t('...') e <Trans> do seu código são adicionados automaticamente ao translation.json. Textos muito curtos, rotas, URLs e templates com variáveis são ignorados.

4. Configure a tradução​

Crie translate.mjs na raiz do projeto. Se você não passar apiKey, será usada a variável de ambiente TRANSLATE_PROJECTS_API_KEY. Se preferir CommonJS, chame-o de translate.cjs e use require.

translate.mjs
import { translateProject } from 'translate-projects-react';

await translateProject({
  sourceLang: 'es', // Idioma base: o idioma padrão do projeto
  targetLangs: ['en', 'pt-BR', 'fr'], // Idiomas a gerar
  outputDir: './public/locales', // Valor padrão
  scanner: true, // Opcional: extrae los textos de ./src
});
OpçãoPadrãoDescrição
sourceLang—Idioma base (obrigatório).
targetLangs—Idiomas a generar.
apiKeyprocess.env.TRANSLATE_PROJECTS_API_KEYAPI token do projeto.
outputDir./public/localesPasta com uma subpasta por idioma.
scannerfalsetrue escanea ./src; { sourceDir: './app' } escanea otra carpeta.

Guarda el token en un archivo .env (fuera de git) y añade el script en package.json. --env-file necesita Node 20.6 o superior; en CI define la variable como secreto:

.env
TRANSLATE_PROJECTS_API_KEY=tu_token
package.json
{
  "scripts": {
    "translate": "node --env-file=.env translate.mjs"
  }
}

5. Traduza​

Terminal
npm run translate

Traducción en la terminal

Arquivos que são gerados​

public/locales/
├── es/translation.json   ← tu idioma base (o el que genera el escáner)
├── en/translation.json   ← gerado
├── pt-BR/translation.json
└── fr/translation.json

Cada archivo conserva la estructura anidada del original. Los idiomas se traducen en paralelo, hasta 3 a la vez.

Autocompletado de claves (opcional)​

src/Title.tsx
import { useTypedTranslation } from 'translate-projects-react/hooks';
import es from '../public/locales/es/translation.json';

export function Title() {
  const { t } = useTypedTranslation<typeof es>();
  return <h1>{t('home.title')}</h1>; // Las claves se autocompletan y se validan
}

Autocompletado de claves

Cache e forçar​

Somente os arquivos e chaves que mudaram são enviados; uma segunda execução sem alterações não traduz nada. Este pacote não tem --force: para traduzir tudo novamente, apague ~/.config/translate-projects-core/cache.json e execute de novo. Mais detalhes em Cache e erros.

Erros comuns​

translateProject devuelve true si todo salió bien. Si algo falla muestra el error real, devuelve false y deja el código de salida en 1, sin cerrar tu proceso.

  • Token inválido (401): revisa TRANSLATE_PROJECTS_API_KEY. Los archivos existentes no se tocan.
  • Falta a key de IA (MISSING_API_KEY): configure o provedor, o modelo e a chave no projeto. Enquanto isso, os textos ficam no idioma base.
  • Tradução parcial: los textos que faltan se piden otra vez en la siguiente ejecución.
  • JSON inválido: si un archivo del idioma base no es JSON válido, no se escribe nada para él.
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.

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! ☕

Buy me a coffee