Alfa
El Compiler de Lingo.dev está en fase alfa. Es inestable, no se recomienda para entornos de producción y sus API pueden cambiar entre versiones.
El Compiler de Lingo.dev se integra con Next.js App Router mediante un wrapper de configuración withLingo() que transforma tu proceso 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.
Prerrequisitos#
Requisitos
- Next.js 14+ con App Router
- Node.js 18+
@lingo.dev/compilerinstalado
Instalación#
pnpm install @lingo.dev/compilerConfigura next.config.ts#
Envuelve la configuración de Next.js con withLingo. La función de configuración debe ser async, ya que 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 Compiler no podrá inicializarse y la compilación fallará. Consulta Solución de problemas para más detalles.
Añade 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 Compiler 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 en el 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 Compiler 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 | Es el bundler predeterminado. No requiere configuración adicional. |
| Turbopack | Completa | Actívalo con next dev --turbopack. El Compiler detecta Turbopack automáticamente. |
Configuración de sourceRoot#
La opción sourceRoot le indica al Compiler qué directorio contiene tus componentes traducibles. En los proyectos con Next.js App Router, normalmente es ./app:
{
sourceRoot: "./app",
}Si tienes componentes fuera de ./app (por ejemplo, en un directorio compartido components/), configura sourceRoot con el directorio padre común:
{
sourceRoot: ".",
}Cuanto más amplio sea sourceRoot, más archivos se analizarán. En proyectos grandes, procura ajustarlo al máximo para reducir los tiempos de compilación. Como alternativa, usa useDirective: true y añade 'use i18n' solo en los archivos que necesiten traducción. Consulta Estructura del proyecto para más detalles.
