Integração com Next.js
Alpha
O Compiler da Lingo.dev está em alpha. É instável, não é recomendado para uso em produção e as APIs podem mudar entre versões.
O Compiler da Lingo.dev integra-se com o App Router do Next.js através de um wrapper de configuração withLingo() que transforma o pipeline de build para gerar bundles por idioma. Suporta React Server Components, Webpack e Turbopack sem exigir alterações ao código dos componentes.
Pré-requisitos#
Requisitos
- Next.js 14+ com App Router
- Node.js 18+
@lingo.dev/compilerinstalado
Instalar#
pnpm install @lingo.dev/compilerConfigurar o next.config.ts#
Envolva a configuração do Next.js com withLingo. A função de configuração tem de ser async — isto é obrigatório porque withLingo faz uma inicialização assíncrona durante o build.
// next.config.ts
import type { NextConfig } from "next";
import { withLingo } from "@lingo.dev/compiler/next";
const nextConfig: NextConfig = {};
export default async function (): Promise<NextConfig> {
return await withLingo(nextConfig, {
sourceRoot: "./app",
sourceLocale: "en",
targetLocales: ["es", "de", "fr", "ja"],
models: "lingo.dev",
dev: {
usePseudotranslator: true,
},
});
}Configuração async obrigatória
A configuração tem de ser exportada como uma função async, e não como um objeto simples. Se exportar um objeto simples, o Compiler não conseguirá inicializar e o build irá falhar. Consulte Troubleshooting para mais detalhes.
Adicionar o LingoProvider#
Envolva o layout raiz com LingoProvider para ativar o contexto de idioma em toda a árvore de componentes:
// app/layout.tsx
import { LingoProvider } from "@lingo.dev/compiler/react";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<LingoProvider>
<html>
<body>{children}</body>
</html>
</LingoProvider>
);
}LingoProvider trata da resolução do idioma, da persistência e do carregamento de dicionários. Funciona tanto com Server Components como com Client Components.
Server Components e Client Components#
O Compiler trata ambos os tipos de componentes de forma transparente:
| Tipo de componente | Como funcionam as traduções |
|---|---|
| React Server Components | As traduções são resolvidas no servidor no momento do pedido. Sem overhead de JS no cliente. |
Client Components ("use client") | As traduções são incluídas no chunk do cliente. useLingoContext() disponível para mudar de idioma. |
| Componentes partilhados | Funcionam em ambos os contextos. O Compiler deteta automaticamente o ambiente de renderização. |
// app/page.tsx - Server Component (default)
export default function Home() {
return <h1>Welcome to our app</h1>;
// Renders translated text with zero client JS
}// app/components/greeting.tsx - Client Component
"use client";
export function Greeting() {
return <p>Hello, world</p>;
// Translations included in client bundle
}Suporte de bundlers#
O wrapper withLingo() funciona com os dois bundlers suportados pelo Next.js:
| Bundler | Suporte | Notas |
|---|---|---|
| Webpack | Completo | Bundler predefinido. Não é necessária qualquer configuração adicional. |
| Turbopack | Completo | Ative com next dev --turbopack. O Compiler deteta automaticamente o Turbopack. |
Configuração de sourceRoot#
A opção sourceRoot indica ao Compiler qual o diretório que contém os componentes traduzíveis. Em projetos com Next.js App Router, normalmente é ./app:
{
sourceRoot: "./app",
}Se tiver componentes fora de ./app (como uma pasta partilhada components/), defina sourceRoot para o diretório principal comum:
{
sourceRoot: ".",
}Um sourceRoot mais abrangente significa que serão analisados mais ficheiros. Em projetos grandes, mantenha-o o mais restrito possível para reduzir os tempos de build. Em alternativa, use useDirective: true e adicione 'use i18n' apenas aos ficheiros que precisam de tradução. Consulte Project Structure para mais detalhes.