Alfa
El Compiler de Lingo.dev está en alfa. Es inestable, no se recomienda para producción y las API pueden cambiar entre versiones.
El Compiler de Lingo.dev se integra con Next.js App Router mediante el wrapper de configuración withLingo(), que transforma tu pipeline de compilación para generar bundles por idioma. Es compatible con React Server Components, Webpack y Turbopack sin necesidad de cambiar el código de tus componentes.
Requisitos previos#
Requisitos
- Next.js 14+ con App Router
- Node.js 18+
@lingo.dev/compilerinstalado
Instalación#
pnpm install @lingo.dev/compilerConfigura next.config.ts#
Envuelve tu configuración de Next.js con withLingo. La función de configuración debe ser async; esto es obligatorio porque withLingo realiza una inicialización asíncrona durante la compilación.
// 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,
},
});
}Se requiere una configuración asíncrona
La configuración debe exportarse como una función async, no como un objeto simple. Si exportas un objeto simple, el compilador no podrá inicializarse y la compilación fallará. Consulta Solución de problemas para más detalles.
Agrega LingoProvider#
Envuelve tu layout raíz con LingoProvider para habilitar el contexto de idioma en todo el árbol 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 se encarga de resolver el idioma, mantenerlo y cargar los diccionarios. Funciona tanto con Server Components como con Client Components.
Server Components y Client Components#
El compilador gestiona ambos tipos de componentes de forma transparente:
| Tipo de componente | Cómo funcionan las traducciones |
|---|---|
| React Server Components | Las traducciones se resuelven en el servidor en el momento de la solicitud. Sin sobrecarga de JS del lado del cliente. |
Client Components ("use client") | Las traducciones se incluyen en el chunk del cliente. useLingoContext() está disponible para cambiar de idioma. |
| Componentes compartidos | Funcionan en ambos contextos. El compilador detecta automáticamente el entorno de renderizado. |
// 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
}Compatibilidad con bundlers#
El wrapper withLingo() funciona con los dos bundlers compatibles con Next.js:
| Bundler | Compatibilidad | Notas |
|---|---|---|
| Webpack | Completa | Bundler predeterminado. No requiere configuración adicional. |
| Turbopack | Completa | Actívalo con next dev --turbopack. El compilador detecta Turbopack automáticamente. |
Configuración de sourceRoot#
La opción sourceRoot le indica al compilador qué directorio contiene tus componentes traducibles. En proyectos con Next.js App Router, normalmente es ./app:
{
sourceRoot: "./app",
}Si tienes componentes fuera de ./app (como un directorio compartido components/), configura sourceRoot en el directorio padre común:
{
sourceRoot: ".",
}Un sourceRoot más amplio implica analizar más archivos. En proyectos grandes, mantenlo lo más acotado posible para reducir los tiempos de compilación. Como alternativa, usa useDirective: true y agrega 'use i18n' solo a los archivos que necesiten traducción. Consulta Estructura del proyecto para más detalles.
