Migrationsleitfaden

Alpha

Der Lingo.dev Compiler befindet sich in der Alpha-Phase. Er ist instabil, nicht für den Produktiveinsatz empfohlen, und die APIs können sich zwischen Releases ändern.

Dieser Leitfaden zeigt, wie Sie vom bisherigen Compiler-Paket lingo.dev auf das aktuelle Paket @lingo.dev/compiler migrieren. Das neue Paket bringt einen npm-Scoped-Namen, eine vereinfachte API, eine pluginbasierte Vite-Integration und ein neues Verzeichnis .lingo/ für Metadaten mit.

Zusammenfassung der Änderungen#

Bereich	Vorher (`lingo.dev`)	Nachher (`@lingo.dev/compiler`)
Paketname	`lingo.dev`	`@lingo.dev/compiler`
Next.js-Integration	Konfiguration direkt anpassen	Asynchroner Wrapper `withLingo()`
Vite-Integration	Manuelle Einrichtung	`lingoCompilerPlugin`
LingoProvider	Prop `loadDictionary` erforderlich	Keine Props erforderlich
Metadatenverzeichnis	`lingo/`	`.lingo/`
Opt-in-Direktive	`'use i18n'` erforderlich	Optional (Standard: alles übersetzen)
Imports	`from "lingo.dev/react"`	`from "@lingo.dev/compiler/react"`

Schritt-für-Schritt-Migration#

Paket ersetzen

Entfernen Sie das alte Paket und installieren Sie das neue:

bash

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

Imports aktualisieren

Ersetzen Sie alle Importpfade:

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

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

Next.js-Konfiguration aktualisieren (falls zutreffend)

Die Next.js-Konfiguration muss jetzt als asynchrone Funktion definiert sein:

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

Der asynchrone Funktions-Wrapper ist erforderlich. Ein synchroner Export führt dazu, dass der Build fehlschlägt. Weitere Details finden Sie unter Next.js Integration.

Vite-Konfiguration aktualisieren (falls zutreffend)

Ersetzen Sie jede manuelle Einrichtung durch 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
  ],
});

LingoProvider vereinfachen

Die Prop loadDictionary wird nicht mehr benötigt. Der Compiler übernimmt das Laden des Wörterbuchs automatisch:

tsx

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

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

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

<LingoProvider>
  <App />
</LingoProvider>

Metadatenverzeichnis verschieben

Benennen Sie das Metadatenverzeichnis von lingo/ in .lingo/ um:

bash

mv lingo/ .lingo/

Aktualisieren Sie Ihre .gitignore, wenn sie noch auf den alten Verzeichnisnamen verweist. Das Verzeichnis .lingo/ sollte in die Versionskontrolle eingecheckt werden.

"use i18n"-Direktiven aktualisieren (optional)

Im neuen Paket ist 'use i18n' optional. Standardmäßig werden alle Dateien in sourceRoot übersetzt. Wenn Sie das Opt-in-Verhalten beibehalten möchten, setzen Sie useDirective: true in Ihrer Konfiguration:

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

Wenn Sie useDirective entfernen (oder auf false setzen), können Sie auch die 'use i18n'-Direktiven aus Ihren Dateien entfernen – alle Dateien in sourceRoot werden dann automatisch übersetzt.

Neu bauen und prüfen

Starten Sie den Entwicklungsserver und vergewissern Sie sich, dass die Übersetzungen angezeigt werden:

bash

npm run dev

Prüfen Sie Folgendes:

Der Pseudotranslator erzeugt [!!! ... !!!]-Marker (falls aktiviert)
Alle zuvor übersetzten Strings funktionieren weiterhin
Die Datei .lingo/metadata.json wird erstellt oder aktualisiert

Nächste Schritte#

Setup

Vollständige Einrichtungsanleitung

Konfigurationsreferenz

Alle neuen Konfigurationsoptionen

Next.js Integration

Next.js-spezifische Details zur Migration

Vite + React

Vite-spezifische Details zur Migration

War diese Seite hilfreich?

Migrationsleitfaden

Alpha

Der Lingo.dev Compiler befindet sich in der Alpha-Phase. Er ist instabil, nicht für den Produktiveinsatz empfohlen, und die APIs können sich zwischen Releases ändern.

Zusammenfassung der Änderungen#

Bereich	Vorher (`lingo.dev`)	Nachher (`@lingo.dev/compiler`)
Paketname	`lingo.dev`	`@lingo.dev/compiler`
Next.js-Integration	Konfiguration direkt anpassen	Asynchroner Wrapper `withLingo()`
Vite-Integration	Manuelle Einrichtung	`lingoCompilerPlugin`
LingoProvider	Prop `loadDictionary` erforderlich	Keine Props erforderlich
Metadatenverzeichnis	`lingo/`	`.lingo/`
Opt-in-Direktive	`'use i18n'` erforderlich	Optional (Standard: alles übersetzen)
Imports	`from "lingo.dev/react"`	`from "@lingo.dev/compiler/react"`

Schritt-für-Schritt-Migration#

Paket ersetzen

Entfernen Sie das alte Paket und installieren Sie das neue:

bash

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

Imports aktualisieren

Ersetzen Sie alle Importpfade:

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

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

Next.js-Konfiguration aktualisieren (falls zutreffend)

Die Next.js-Konfiguration muss jetzt als asynchrone Funktion definiert sein:

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

Der asynchrone Funktions-Wrapper ist erforderlich. Ein synchroner Export führt dazu, dass der Build fehlschlägt. Weitere Details finden Sie unter Next.js Integration.

Vite-Konfiguration aktualisieren (falls zutreffend)

Ersetzen Sie jede manuelle Einrichtung durch 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
  ],
});

LingoProvider vereinfachen

Die Prop loadDictionary wird nicht mehr benötigt. Der Compiler übernimmt das Laden des Wörterbuchs automatisch:

tsx

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

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

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

<LingoProvider>
  <App />
</LingoProvider>

Metadatenverzeichnis verschieben

Benennen Sie das Metadatenverzeichnis von lingo/ in .lingo/ um:

bash

mv lingo/ .lingo/

Aktualisieren Sie Ihre .gitignore, wenn sie noch auf den alten Verzeichnisnamen verweist. Das Verzeichnis .lingo/ sollte in die Versionskontrolle eingecheckt werden.

"use i18n"-Direktiven aktualisieren (optional)

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

Neu bauen und prüfen

Starten Sie den Entwicklungsserver und vergewissern Sie sich, dass die Übersetzungen angezeigt werden:

bash

npm run dev

Prüfen Sie Folgendes:

Der Pseudotranslator erzeugt [!!! ... !!!]-Marker (falls aktiviert)
Alle zuvor übersetzten Strings funktionieren weiterhin
Die Datei .lingo/metadata.json wird erstellt oder aktualisiert

Nächste Schritte#

Setup

Vollständige Einrichtungsanleitung

Konfigurationsreferenz

Alle neuen Konfigurationsoptionen

Next.js Integration

Next.js-spezifische Details zur Migration

Vite + React

Vite-spezifische Details zur Migration

War diese Seite hilfreich?