开发工具

@lingo.dev/compiler 提供开发工具，可加快您的工作流程并在开发过程中降低 API 成本。

伪翻译器

伪翻译器可即时生成虚拟翻译，无需 API 调用。

启用

{
  dev: {
    usePseudotranslator: true,
  }
}

功能说明

通过视觉标记转换文本：

原文：

Welcome to our app

伪翻译：

[!!! Ẃëļċöṁë ẗö öüř äþþ !!!]

优势：

  1. 即时反馈 — 无需 API 调用，无需等待
  2. 可视化可翻译文本 — 精确查看哪些内容会被翻译
  3. 测试不同长度 — 伪翻译文本约长 30%，可暴露布局问题
  4. 零成本 — 不消耗 API 配额

工作原理

伪翻译器：

  • 添加标记（[!!! 和 !!!]）
  • 用带变音符号的字符替换原字符（a → ä，e → ë）
  • 文本长度增加约 30%
  • 保留插值内容（{name} 保持不变）
  • 保持 HTML 结构不变

带插值的示例：

<p>Hello {name}, you have {count} items</p>
// Becomes: [!!! Ḧëļļö {name}, ÿöü ḧävë {count} ïẗëṁṡ !!!]

适用场景

开发阶段：

  • 初始设置与集成
  • 使用不同文本长度进行布局测试
  • 调试翻译相关问题
  • 快速迭代 UI

不适用场景：

  • 审查实际翻译质量
  • 测试特定语言格式
  • 上线前的最终 QA

真实翻译时请禁用

{
  dev: {
    usePseudotranslator: false,
  }
}

重启开发服务器以使用您配置的 LLM 提供商生成真实翻译。

翻译服务器

翻译服务器在开发过程中处理按需翻译生成。

工作原理

当你运行 npm run dev 时：

  1. 编译器会启动本地 HTTP 服务器
  2. 服务器会自动查找可用端口（60000-60099）
  3. 你的应用会从服务器请求翻译内容
  4. 服务器生成翻译（伪翻译或真实翻译）
  5. 翻译内容会缓存在 .lingo/metadata.json 中

配置

{
  dev: {
    translationServerStartPort: 60000, // Starting port
    translationServerUrl: "http://localhost:60000", // Custom URL (advanced)
  }
}

端口范围： 服务器会依次尝试 60000-60099 端口，直到找到可用端口。

手动启动（高级）

你可以手动启动翻译服务器：

npx @lingo.dev/compiler translate-server \
  --port 60000 \
  --config ./lingo.config.json

适用于以下场景：

  • 将翻译服务器与构建流程分离运行
  • 调试翻译相关问题
  • 自定义 CI/CD 工作流

WebSocket 支持

翻译服务器支持 WebSocket，可与开发小组件进行实时通信。

当翻译内容更新时，服务器会通过 WebSocket 向已连接的客户端推送变更。

开发小组件

开发小组件是在浏览器中实时编辑翻译内容的叠加层。

功能

  • 浏览器内编辑翻译 — 无需编辑文件
  • 查看上下文 — 查看源文本、组件位置
  • 实时更新 — 通过 WebSocket 立即应用更改
  • 切换语言环境 — 快速测试不同语言环境

启用

{
  dev: {
    enableWidget: true, // Coming soon
  }
}

状态： 开发小组件正在积极开发中，将在未来版本中提供。

工作方式预览

  1. 按下快捷键（如 Cmd+Shift+L）
  2. 小组件叠加层出现
  3. 点击任意已翻译文本进行编辑
  4. 针对特定语言环境修改翻译
  5. 保存——更改通过 WebSocket 同步
  6. 翻译内容会立即在 .lingo/metadata.json 中更新

开发工作流

推荐配置

1. 初始配置：

{
  dev: {
    usePseudotranslator: true, // Fast feedback
  }
}

运行 npm run dev 可立即查看伪翻译效果。

2. 布局测试：

伪翻译可揭示布局问题：

  • 文本溢出
  • 标签被截断
  • 元素未对齐
  • 响应式断点设置不正确

在投入真实翻译前，先修复布局问题。

3. 真实翻译审核：

{
  dev: {
    usePseudotranslator: false,
  }
}

生成真实翻译以审核质量。请测试：

  • 翻译准确性
  • 语气与正式程度
  • 技术术语处理
  • 品牌名称保留

4. 精细调整：

使用 data-lingo-override 进行精确控制：

<h1 data-lingo-override={{ es: "Bienvenido", de: "Willkommen" }}>
  Welcome
</h1>

5. 生产构建：

{
  buildMode: "cache-only",
}

使用预生成的翻译以实现快速、可复现的构建。

调试

检查翻译服务器

翻译服务器日志输出到控制台：

[lingo] Translation server started on port 60001
[lingo] Pseudotranslator: enabled
[lingo] Watching for changes...

检查元数据文件

检查 .lingo/metadata.json 以查看缓存的翻译：

{
  "translations": {
    "abc123": {
      "source": "Welcome to our app",
      "locales": {
        "es": "[!!! Ẃëļċöṁë ẗö öüř äþþ !!!]",
        "de": "[!!! Ẃëļċöṁë ẗö öüř äþþ !!!]"
      }
    }
  }
}

禁用伪翻译器后，将显示真实翻译。

端口冲突

如果 60000-60099 端口全部被占用：

{
  dev: {
    translationServerStartPort: 61000, // Use different range
  }
}

或者手动停止使用这些端口的进程：

# Find process using port 60000
lsof -i :60000

# Kill process
kill -9 <PID>

性能优化建议

伪翻译器速度极快 — 开发环境下建议默认使用。

真实翻译速度较慢 — 仅在需要检查翻译质量时使用：

  • 初次生成翻译：受 API 延迟影响
  • 后续构建：翻译结果缓存，速度很快

翻译服务器资源占用极低 — 内存和 CPU 占用最小。

常见问题

需要手动启动翻译服务器吗？ 不需要。运行 npm run dev 时会自动启动。

可以在生产环境中使用伪翻译器吗？ 不可以。伪翻译器仅用于开发环境。生产构建始终使用 .lingo/metadata.json 中的真实翻译。

为什么开发小组件还不可用？ 该功能正在开发中。请关注 GitHub 发布页 获取最新动态。

可以自定义伪翻译内容吗？ 目前不支持。伪翻译器采用固定算法，专为可视化可翻译文本而优化。

伪翻译支持所有字符集吗？ 支持。伪翻译器可正确处理 Unicode，包括 emoji、CJK 字符和 RTL 语言。

后续操作