Guía de migración

Alfa

El Compiler de Lingo.dev está en fase alfa. Es inestable, no se recomienda para producción y las API pueden cambiar entre versiones.

Esta guía explica cómo migrar del paquete anterior del compilador lingo.dev al paquete actual @lingo.dev/compiler. El nuevo paquete incorpora un nombre de npm con scope, una API simplificada, integración con Vite basada en plugins y un nuevo directorio .lingo/ para metadatos.

Resumen de cambios#

Área	Antes (`lingo.dev`)	Ahora (`@lingo.dev/compiler`)
Nombre del paquete	`lingo.dev`	`@lingo.dev/compiler`
Integración con Next.js	Modificación directa de la configuración	Wrapper asíncrono de `withLingo()`
Integración con Vite	Configuración manual	`lingoCompilerPlugin`
LingoProvider	Requiere la prop `loadDictionary`	No requiere props
Directorio de metadatos	`lingo/`	`.lingo/`
Directiva de activación	`'use i18n'` obligatoria	Opcional (predeterminado: traducir todo)
Importaciones	`from "lingo.dev/react"`	`from "@lingo.dev/compiler/react"`

Migración paso a paso#

Reemplaza el paquete

Elimina el paquete anterior e instala el nuevo:

bash

npm uninstall lingo.dev
npm install @lingo.dev/compiler

Actualiza las importaciones

Reemplaza todas las rutas de importación:

// Before
import { LingoProvider, useLingoContext } from "lingo.dev/react";

// After
import { LingoProvider, useLingoContext } from "@lingo.dev/compiler/react";

Actualiza la configuración de Next.js (si corresponde)

La configuración de Next.js ahora debe ser una función asíncrona:

// Before
import { withLingo } from "lingo.dev/next";
const nextConfig = {};
export default withLingo(nextConfig, { /* options */ });

// After
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"],
    models: "lingo.dev",
  });
}

El wrapper de función asíncrona es obligatorio. Una exportación síncrona hará que falle el build. Consulta Integración con Next.js para más detalles.

Actualiza la configuración de Vite (si corresponde)

Reemplaza cualquier configuración manual por lingoCompilerPlugin:

// 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"],
      models: "lingo.dev",
    }),
    react(), // Must come AFTER lingoCompilerPlugin
  ],
});

Simplifica LingoProvider

La prop loadDictionary ya no es necesaria. El compilador se encarga automáticamente de cargar el diccionario:

tsx

// Before
import { LingoProvider } from "lingo.dev/react";

<LingoProvider loadDictionary={loadDictionary}>
  <App />
</LingoProvider>

// After
import { LingoProvider } from "@lingo.dev/compiler/react";

<LingoProvider>
  <App />
</LingoProvider>

Mueve el directorio de metadatos

Renombra el directorio de metadatos de lingo/ a .lingo/:

bash

mv lingo/ .lingo/

Actualiza tu .gitignore si hace referencia al nombre anterior del directorio. El directorio .lingo/ debe incluirse en el control de versiones.

Actualiza las directivas 'use i18n' (opcional)

En el nuevo paquete, 'use i18n' es opcional. De forma predeterminada, se traducen todos los archivos en sourceRoot. Si quieres mantener el comportamiento opt-in, configura useDirective: true en tu configuración:

{
  useDirective: true, // Keep requiring 'use i18n' in each file
}

Si eliminas useDirective (o lo configuras como false), también puedes quitar las directivas 'use i18n' de tus archivos: todos los archivos en sourceRoot se traducirán automáticamente.

Vuelve a compilar y verifica

Inicia el servidor de desarrollo y verifica que las traducciones aparezcan correctamente:

bash

npm run dev

Comprueba que:

El pseudotraductor genere marcadores [!!! ... !!!] (si está habilitado)
Todas las cadenas traducidas anteriormente sigan funcionando
El archivo .lingo/metadata.json se cree o actualice

Próximos pasos#

Configuración

Guía completa de configuración

Referencia de configuración

Todas las nuevas opciones de configuración

Integración con Next.js

Detalles de migración específicos de Next.js

Vite + React

Detalles de migración específicos de Vite