Alpha
O Compiler da Lingo.dev está em alpha. É instável, não é recomendado para utilização em produção e as APIs podem mudar entre versões.
O Compiler da Lingo.dev integra com o Vite através de lingoCompilerPlugin, um plugin do Vite que transforma os seus componentes React durante a build para injetar traduções. Suporta Hot Module Replacement completo, por isso as traduções são atualizadas de imediato durante o desenvolvimento.
Pré-requisitos#
Requisitos
- Vite 5+ com React
- Node.js 18+
@lingo.dev/compilerinstalado
Instalação#
pnpm install @lingo.dev/compilerConfigurar o vite.config.ts#
Adicione lingoCompilerPlugin à configuração do Vite. O plugin tem de ser colocado antes do plugin react() — esta ordem é obrigatória porque o compiler precisa de transformar o JSX antes de o plugin do React o processar.
// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { lingoCompilerPlugin } from "@lingo.dev/compiler/vite";
export default defineConfig({
plugins: [
lingoCompilerPlugin({
sourceRoot: "src",
sourceLocale: "en",
targetLocales: ["es", "de", "fr", "ja"],
models: "lingo.dev",
dev: {
usePseudotranslator: true,
},
}),
react(),
],
});A ordem dos plugins é importante
Se lingoCompilerPlugin for colocado depois de react(), o plugin do React processa primeiro o JSX e o compiler deixa de conseguir identificar texto traduzível. Coloque sempre o plugin da Lingo primeiro no array plugins.
Adicionar o LingoProvider#
Envolva a raiz da aplicação com LingoProvider no ficheiro de entrada:
// src/main.tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { LingoProvider } from "@lingo.dev/compiler/react";
import App from "./App";
createRoot(document.getElementById("root")!).render(
<StrictMode>
<LingoProvider>
<App />
</LingoProvider>
</StrictMode>
);LingoProvider inicializa o contexto de idioma e carrega o dicionário de traduções adequado para o idioma ativo.
Hot Module Replacement#
O plugin integra com o sistema HMR do Vite. Quando edita texto traduzível num componente:
Editar o texto de origem
Altere qualquer texto no JSX — por exemplo, atualize um título de "Boas-vindas" para "Boas-vindas de volta".
O Compiler deteta a alteração
O plugin interceta a atualização HMR, identifica a string alterada e gera uma nova tradução (ou pseudotradução em modo de desenvolvimento).
O browser atualiza de imediato
O componente traduzido volta a ser renderizado sem recarregar a página por completo. Os metadados de tradução em .lingo/metadata.json são atualizados em disco.
Configuração de sourceRoot#
A opção sourceRoot determina que ficheiros o compiler analisa à procura de texto traduzível. Para um projeto Vite + React standard:
{
sourceRoot: "src",
}| Estrutura do projeto | sourceRoot recomendado |
|---|---|
Standard (src/) | "src" |
| Monorepo com packages partilhados | "." (raiz do projeto) |
| Diretório personalizado | Caminho para a diretoria dos componentes |
Em bases de código maiores, um sourceRoot mais restrito reduz os tempos de build. Se só precisar de traduções em ficheiros específicos, ative useDirective: true e adicione 'use i18n' a esses ficheiros. Consulte Estrutura do projeto.
Exemplo de estrutura do projeto#
my-vite-app/
src/
main.tsx # LingoProvider wraps <App />
App.tsx # Translatable components
components/
Header.tsx # Automatically scanned
Footer.tsx # Automatically scanned
.lingo/
metadata.json # Translation cache (commit this)
vite.config.ts # lingoCompilerPlugin configured here