Alpha
Lingo.dev Compiler 目前仍处于 alpha 阶段，稳定性尚未完善，不建议用于生产环境，且 API 可能会在不同版本之间发生变化。
本指南将带你从旧版 lingo.dev compiler 包迁移到当前的 @lingo.dev/compiler 包。新包采用了带作用域的 npm 包名，提供更简洁的 API、基于插件的 Vite 集成，以及用于存放元数据的全新 .lingo/ 目录。
变更概览#
| 项目 | 迁移前（lingo.dev） | 迁移后（@lingo.dev/compiler） |
|---|---|---|
| 包名 | lingo.dev | @lingo.dev/compiler |
| Next.js 集成 | 直接修改配置 | withLingo() 异步包装器 |
| Vite 集成 | 手动配置 | lingoCompilerPlugin |
| LingoProvider | 必须传入 loadDictionary 属性 | 无需传入属性 |
| 元数据目录 | lingo/ | .lingo/ |
| 按需启用指令 | 必须使用 'use i18n' | 可选（默认：全部翻译） |
| 导入方式 | from "lingo.dev/react" | from "@lingo.dev/compiler/react" |
迁移步骤#
1
替换包
移除旧包并安装新包：
bash
npm uninstall lingo.dev
npm install @lingo.dev/compiler2
更新导入
将所有导入路径替换为：
ts
// Before
import { LingoProvider, useLingoContext } from "lingo.dev/react";
// After
import { LingoProvider, useLingoContext } from "@lingo.dev/compiler/react";3
更新 Next.js 配置（如适用）
现在，Next.js 配置必须改为异步函数：
ts
// 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",
});
}异步函数包装器是必需的；如果继续使用同步导出，构建将会失败。详情请参阅 Next.js Integration。
4
更新 Vite 配置（如适用）
将所有手动配置替换为 lingoCompilerPlugin：
ts
// 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
],
});5
简化 LingoProvider
现在无需再传入 loadDictionary 属性，Compiler 会自动处理字典加载：
tsx
// Before
import { LingoProvider } from "lingo.dev/react";
<LingoProvider loadDictionary={loadDictionary}>
<App />
</LingoProvider>
// After
import { LingoProvider } from "@lingo.dev/compiler/react";
<LingoProvider>
<App />
</LingoProvider>6
迁移元数据目录
将元数据目录从 lingo/ 重命名为 .lingo/：
bash
mv lingo/ .lingo/如果你的 .gitignore 中仍引用旧目录名，请一并更新。.lingo/ 目录应提交到版本控制中。
7
更新“use i18n”指令（可选）
在新包中，'use i18n' 变为可选。默认情况下，sourceRoot 中的所有文件都会被翻译。如果你希望保留按需启用的行为，请在配置中设置 useDirective: true：
ts
{
useDirective: true, // Keep requiring 'use i18n' in each file
}如果你移除了 useDirective（或将其设为 false），也可以一并删除文件中的 'use i18n' 指令——sourceRoot 中的所有文件都会自动翻译。
8
重新构建并验证
启动开发服务器，确认翻译已正常显示：
bash
npm run dev请检查以下内容：
- 伪翻译器会生成
[!!! ... !!!]标记（如已启用） - 此前已翻译的所有字符串仍可正常工作
.lingo/metadata.json文件已创建或已更新
