Alpha
O Compiler da Lingo.dev está em alpha. Ele é instável, não é recomendado para uso em produção, e as APIs podem mudar entre versões.
O Compiler da Lingo.dev se integra ao Vite por meio de lingoCompilerPlugin, um plugin do Vite que transforma seus componentes React no build para injetar traduções. Ele oferece suporte completo a Hot Module Replacement, então as traduções são atualizadas instantaneamente durante o desenvolvimento.
Pré-requisitos#
Requisitos
- Vite 5+ com React
- Node.js 18+
@lingo.dev/compilerinstalado
Instalação#
pnpm install @lingo.dev/compilerConfigure o vite.config.ts#
Adicione lingoCompilerPlugin à configuração do Vite. O plugin deve vir antes do plugin react() — essa ordem é obrigatória, porque o compilador precisa transformar o JSX antes que o plugin do React o processe.
// 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 importa
Se lingoCompilerPlugin vier depois de react(), o plugin do React processará o JSX primeiro, e o compilador não conseguirá identificar o texto traduzível. Sempre coloque o plugin da Lingo primeiro no array plugins.
Adicione o LingoProvider#
Envolva a raiz da aplicação com LingoProvider no arquivo 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 apropriado para o idioma ativo.
Hot Module Replacement#
O plugin se integra ao sistema de HMR do Vite. Quando você edita texto traduzível em um componente:
Edite o texto-fonte
Altere qualquer texto no JSX — por exemplo, atualize um título de "Boas-vindas" para "Boas-vindas de volta".
O Compiler detecta a mudança
O plugin intercepta a atualização de HMR, identifica a string alterada e gera uma nova tradução (ou pseudotradução no modo de desenvolvimento).
O navegador atualiza na hora
O componente traduzido é renderizado novamente 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 quais arquivos o compilador analisa em busca de texto traduzível. Para um projeto Vite + React padrão:
{
sourceRoot: "src",
}| Estrutura do projeto | sourceRoot recomendado |
|---|---|
Padrão (src/) | "src" |
| Monorepo com pacotes compartilhados | "." (raiz do projeto) |
| Diretório personalizado | Caminho para o diretório dos componentes |
Em bases de código grandes, um sourceRoot mais restrito reduz o tempo de build. Se você só precisa de traduções em arquivos específicos, habilite useDirective: true e adicione 'use i18n' a esses arquivos. 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