Migration Guide

Max Prilutskiy·Updated 5 days ago·3 min read

Alpha

The Lingo.dev Compiler is in alpha. It is unstable, not recommended for production use, and APIs may change between releases.

This guide covers migrating from the previous lingo.dev compiler package to the current @lingo.dev/compiler package. The new package introduces a scoped npm name, simplified API, plugin-based Vite integration, and a new .lingo/ directory for metadata.

Summary of changes#

Area	Before (`lingo.dev`)	After (`@lingo.dev/compiler`)
Package name	`lingo.dev`	`@lingo.dev/compiler`
Next.js integration	Direct config modification	`withLingo()` async wrapper
Vite integration	Manual setup	`lingoCompilerPlugin`
LingoProvider	Required `loadDictionary` prop	No props needed
Metadata directory	`lingo/`	`.lingo/`
Opt-in directive	`'use i18n'` required	Optional (default: translate all)
Imports	`from "lingo.dev/react"`	`from "@lingo.dev/compiler/react"`

Step-by-step migration#

Replace the package

Remove the old package and install the new one:

bash

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

Update imports

Replace all import paths:

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

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

Update Next.js config (if applicable)

The Next.js config must now be an async function:

// 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",
  });
}

The async function wrapper is required. A synchronous export will cause the build to fail. See Next.js Integration for details.

Update Vite config (if applicable)

Replace any manual setup with the 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
  ],
});

Simplify LingoProvider

The loadDictionary prop is no longer needed. The compiler handles dictionary loading automatically:

tsx

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

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

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

<LingoProvider>
  <App />
</LingoProvider>

Move metadata directory

Rename the metadata directory from lingo/ to .lingo/:

bash

mv lingo/ .lingo/

Update your .gitignore if it references the old directory name. The .lingo/ directory should be committed to version control.

Update 'use i18n' directives (optional)

In the new package, 'use i18n' is optional. By default, all files in sourceRoot are translated. If you want to keep opt-in behavior, set useDirective: true in your config:

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

If you remove useDirective (or set it to false), you can also remove the 'use i18n' directives from your files - all files in sourceRoot will be translated automatically.

Rebuild and verify

Run the dev server and verify translations appear:

bash

npm run dev

Check that:

The pseudotranslator produces [!!! ... !!!] markers (if enabled)
All previously translated strings still work
The .lingo/metadata.json file is created or updated

Next Steps#

Setup

Full setup walkthrough

Configuration Reference

All new configuration options

Next.js Integration

Next.js-specific migration details

Vite + React

Vite-specific migration details

Was this page helpful?

Migration Guide

Max Prilutskiy·Updated 5 days ago·3 min read

Alpha

The Lingo.dev Compiler is in alpha. It is unstable, not recommended for production use, and APIs may change between releases.

Summary of changes#

Area	Before (`lingo.dev`)	After (`@lingo.dev/compiler`)
Package name	`lingo.dev`	`@lingo.dev/compiler`
Next.js integration	Direct config modification	`withLingo()` async wrapper
Vite integration	Manual setup	`lingoCompilerPlugin`
LingoProvider	Required `loadDictionary` prop	No props needed
Metadata directory	`lingo/`	`.lingo/`
Opt-in directive	`'use i18n'` required	Optional (default: translate all)
Imports	`from "lingo.dev/react"`	`from "@lingo.dev/compiler/react"`

Step-by-step migration#

Replace the package

Remove the old package and install the new one:

bash

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

Update imports

Replace all import paths:

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

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

Update Next.js config (if applicable)

The Next.js config must now be an async function:

// 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",
  });
}

The async function wrapper is required. A synchronous export will cause the build to fail. See Next.js Integration for details.

Update Vite config (if applicable)

Replace any manual setup with the 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
  ],
});

Simplify LingoProvider

The loadDictionary prop is no longer needed. The compiler handles dictionary loading automatically:

tsx

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

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

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

<LingoProvider>
  <App />
</LingoProvider>

Move metadata directory

Rename the metadata directory from lingo/ to .lingo/:

bash

mv lingo/ .lingo/

Update your .gitignore if it references the old directory name. The .lingo/ directory should be committed to version control.

Update 'use i18n' directives (optional)

In the new package, 'use i18n' is optional. By default, all files in sourceRoot are translated. If you want to keep opt-in behavior, set useDirective: true in your config:

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

If you remove useDirective (or set it to false), you can also remove the 'use i18n' directives from your files - all files in sourceRoot will be translated automatically.

Rebuild and verify

Run the dev server and verify translations appear:

bash

npm run dev

Check that:

The pseudotranslator produces [!!! ... !!!] markers (if enabled)
All previously translated strings still work
The .lingo/metadata.json file is created or updated

Next Steps#

Setup

Full setup walkthrough

Configuration Reference

All new configuration options

Next.js Integration

Next.js-specific migration details

Vite + React

Vite-specific migration details

Was this page helpful?