故障排查

使用 @lingo.dev/compiler 时的常见问题及解决方案。

安装问题

“找不到模块 '@lingo.dev/compiler'”

原因： 未安装或安装包不正确。

解决方法：

npm install @lingo.dev/compiler
# or
pnpm install @lingo.dev/compiler

验证安装：

ls node_modules/@lingo.dev/compiler

“找不到模块：无法解析 '@lingo.dev/compiler/react'”

原因： 导入路径错误或包版本过旧。

解决方法：

  1. 检查导入语句：

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

  2. 重新安装包：

    rm -rf node_modules
npm install

配置问题

“Config 必须为 async 函数”（Next.js）

原因： Next.js 配置未用 async 函数包裹。

解决方法：

// Wrong
export default withLingo(nextConfig, {...});

// Correct
export default async function (): Promise<NextConfig> {
  return await withLingo(nextConfig, {...});
}

“sourceLocale 是必需的”

原因： 配置中缺少 sourceLocale。

解决方法：

{
  sourceLocale: "en", // Required
  targetLocales: ["es", "de"],
}

“targetLocales 必须为数组”

原因： targetLocales 不是数组或为空。

解决方案：

{
  targetLocales: ["es", "de"], // Must be array with at least one locale
}

翻译问题

翻译未显示

症状： 仅显示源语言文本。

原因与解决方案：

1. 未添加 LingoProvider 或位置不正确

// Wrong - too low in tree
export default function Page() {
  return (
    <LingoProvider>
      <Content />
    </LingoProvider>
  );
}

// Correct - in root layout
export default function RootLayout({ children }) {
  return (
    <LingoProvider>
      <html>
        <body>{children}</body>
      </html>
    </LingoProvider>
  );
}

2. 元数据中缺少翻译 请检查 .lingo/metadata.json：

{
  "translations": {
    "abc123": {
      "locales": {
        "es": "..." // Should have translation
      }
    }
  }
}

如为空或缺失，请使用 buildMode: "translate" 运行：

npm run dev # or build

3. 构建模式为仅缓存但无缓存翻译

# Generate translations first
LINGO_BUILD_MODE=translate npm run build

# Then use cache-only
LINGO_BUILD_MODE=cache-only npm run build

所有翻译均为 "[!!! ...]"

原因： 启用了伪翻译器。

解决方案：

{
  dev: {
    usePseudotranslator: false, // Disable for real translations
  }
}

重启开发服务器。

部分文本未被翻译

原因：

1. 动态内容或 props

// Not translated (yet) - string in variable
const title = "Welcome";
<h1>{title}</h1>

// Translated - string in JSX
<h1>Welcome</h1>

解决方案： 编译器正在增强以支持字符串字面量。目前请将文本直接写入 JSX。

2. 属性中的文本需要特殊处理

// Translated automatically
<img alt="Logo" />
<button aria-label="Close" />

// May need explicit handling
<div custom-attr="Some text" /> // Not translated unless configured

3. 已启用 useDirective 如果 useDirective: true，则没有 'use i18n' 的文件不会被翻译。

**解决方案：**添加指令：

'use i18n';

export function Component() { ... }

构建问题

“缺少语言 X 的翻译”

原因：buildMode: "cache-only"，但缺少翻译。

解决方案：

  1. 生成翻译：

    npm run dev # or
LINGO_BUILD_MODE=translate npm run build

  2. 提交 .lingo/metadata.json

  3. 使用 cache-only 重试

“生成翻译失败”

可能原因：

1. API 密钥无效

# Check .env file
cat .env | grep API_KEY

请确保 API 密钥与您的服务商匹配。

2. 网络问题 测试 API 连接：

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

3. 速率限制 请降低翻译生成速度或升级 API 等级。

4. 模型配置无效

// Wrong
{
  models: {
    "*:*": "invalid-provider:model",
  }
}

// Correct
{
  models: {
    "*:*": "groq:llama-3.3-70b-versatile",
  }
}

构建速度慢

可能原因：

1. 正在生成大量翻译 首次构建新文本时速度较慢，后续构建会更快（有缓存）。

2. 开发环境下伪翻译器未启用

{
  dev: {
    usePseudotranslator: true, // Enable for fast development
  }
}

3. 不必要地启用了复数处理

{
  pluralization: {
    enabled: false, // Disable if not using plural forms
  }
}

HMR 问题

HMR 无法正常工作

原因： LingoProvider 放置位置或框架配置问题。

解决方案：

Next.js： 确保 LingoProvider 位于根布局中，而不是嵌套布局。

Vite： 确保 lingoCompilerPlugin 插件放在 react() 插件之前：

plugins: [
  lingoCompilerPlugin({...}), // Before react plugin
  react(),
]

语言切换时状态重置

原因： 由于切换语言导致页面重新加载。

预期行为： setLocale() 默认会重新加载页面以应用新语言。

避免重新加载的方法： 实现自定义 persistLocale，无需重新加载：

// .lingo/locale-resolver.client.ts
export function persistLocale(locale: string): void {
  localStorage.setItem("locale", locale);
  // Don't call window.location.reload()
}

注意：这需要预加载所有语言的翻译内容。

API/认证问题

"API key 无效"

解决方案：

1. 检查环境变量名称

# Lingo.dev Engine
LINGODOTDEV_API_KEY=...

# OpenAI
OPENAI_API_KEY=sk-...

# Anthropic
ANTHROPIC_API_KEY=sk-ant-...

2. 验证 API key 是否已激活 登录到 provider 控制台并检查 key 状态。

3. 添加 key 后重启开发服务器

npm run dev

环境变量在启动时加载。

“身份验证失败” (Lingo.dev)

解决方案：

1. 重新认证

npx lingo.dev@latest login

2. 手动 API key

# Add to .env
LINGODOTDEV_API_KEY=your_key_here

请在 lingo.dev 项目设置中获取 key。

浏览器阻止认证流程

原因： Brave 浏览器或扩展程序阻止了身份验证。

解决方案： 手动将 API key 添加到 .env：

LINGODOTDEV_API_KEY=...

服务器问题

“翻译服务器启动失败”

原因： 端口 60000-60099 全部被占用。

解决方案：

1. 配置不同的端口范围

{
  dev: {
    translationServerStartPort: 61000,
  }
}

2. 结束已有进程

# Find processes using ports
lsof -i :60000-60099

# Kill process
kill -9 <PID>

“端口 60000 已被占用”

原因： 该端口已被其他进程占用。

解决方案： 服务器会自动查找下一个可用端口。请在控制台查看实际端口：

[lingo] Translation server started on port 60001

如果所有端口都被占用，请参见上方“翻译服务器启动失败”。

类型错误

“属性 'data-lingo-override' 不存在”

原因： TypeScript 无法识别该属性。

解决方案： 添加类型声明：

// global.d.ts
declare namespace React {
  interface HTMLAttributes<T> {
    "data-lingo-override"?: Record<string, string>;
  }
}

或者使用引号：

<div {"data-lingo-override"}={{ es: "..." }}>
  Text
</div>

“类型错误：Config 必须返回 Promise”

原因： Next.js 配置类型不正确。

解决方案：

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, {...});
}

生产环境问题

生产环境缺少翻译

可能原因：

1. .lingo/ 未提交

git add .lingo/
git commit -m "chore: add translations"
git push

2. 生产构建模式错误

// Should be cache-only in production
{
  buildMode: "cache-only",
}

3. CI 未生成翻译 请检查 CI 日志，确保翻译已生成并提交。

开发与生产环境翻译不一致

原因： 生产环境启用了伪翻译器。

解决方案：

{
  dev: {
    usePseudotranslator: process.env.NODE_ENV === "development", // Only in dev
  }
}

获取帮助

如果你仍然遇到问题：

  1. 检查日志 — 查看控制台中的错误信息
  2. 检查 .lingo/metadata.json — 验证结构和内容
  3. 使用伪翻译器测试 — 排查 API 问题
  4. 查看 GitHub issues — github.com/lingodotdev/lingo.dev/issues
  5. 在 Discord 上提问 — discord.gg/lingo

在寻求帮助时，请提供：

  • 错误信息（完整堆栈跟踪）
  • 配置文件（next.config.ts 或 vite.config.ts）
  • 包版本（npm list @lingo.dev/compiler）
  • 复现步骤

常见问题

问：生产环境需要 API 密钥吗？ 答：不需要，使用 buildMode: "cache-only"。翻译会在 CI 中预生成。

问：为什么我的构建失败了？ 答：请检查错误信息。常见原因包括：缺少翻译、API 密钥无效、网络问题。

问：可以使用多个 LLM 提供商吗？ 答：可以，在 models 配置中通过 locale-pair 映射实现。

问：如何在不产生 API 费用的情况下测试？ 答：在开发环境中启用 usePseudotranslator: true。

后续步骤