Guía de migración

Alpha

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

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

Resumen de los cambios#

Área	Antes (`lingo.dev`)	Después (`@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	Prop `loadDictionary` obligatoria	No requiere props
Directorio de metadatos	`lingo/`	`.lingo/`
Directiva opcional de activación	`'use i18n'` obligatoria	Opcional (por defecto: traducir todo)
Importaciones	`from "lingo.dev/react"`	`from "@lingo.dev/compiler/react"`

Migración paso a paso#

Sustituye el paquete

Elimina el paquete anterior e instala el nuevo:

bash

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

Actualiza las importaciones

Sustituye 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)

Ahora la configuración de Next.js 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 la compilación falle. Consulta Next.js Integration para más información.

Actualiza la configuración de Vite (si corresponde)

Sustituye 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 Compiler se encarga de cargar el diccionario automáticamente:

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

Cambia el nombre del 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. Por defecto, se traducen todos los archivos de sourceRoot. Si quieres mantener el comportamiento de activación opcional, establece useDirective: true en tu configuración:

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

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

Vuelve a compilar y compruébalo

Inicia el servidor de desarrollo y comprueba que aparezcan las traducciones:

bash

npm run dev

Comprueba que:

El pseudotraductor genera marcadores [!!! ... !!!] (si está activado)
Todas las cadenas traducidas anteriormente siguen funcionando
El archivo .lingo/metadata.json se crea o se actualiza

Siguientes 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