常见问题

关于 Lingo.dev Compiler 的常见问题和解答。

我可以翻译字符串字面量吗？

Lingo.dev Compiler 遵循的约定是，JSX 中的所有内容都是可本地化的。设计上，JSX 组件之外的字符串字面量不会被本地化。

当前行为：

// 这段代码不会被翻译
const message = "Hello world";
const errorText = "Something went wrong";

// 这段代码会被翻译
function Component() {
  return <h1>Hello world</h1>;
}

使字面量可本地化：

您可以通过将字符串字面量包装在 JSX 片段中来使其可本地化：

// 之前：不可本地化
const message = "Hello world";

// 之后：使用片段使其可本地化
const message = <>Hello world</>;

// 在组件中使用
function Component() {
  return <div>{message}</div>;
}

替代方法：

// 对于动态消息
function getLocalizedMessage() {
  return <>Something went wrong</>;
}

// 对于条件文本
const statusText = isError ? <>Error occurred</> : <>Success</>;

此约定确保了本地化行为的一致性，同时保持了可本地化内容与不可本地化内容之间的清晰界限。

我们正在探索扩展此行为以支持更多用例的方法。欢迎加入我们的 Discord 社区 讨论您希望支持的特定模式。

支持哪些框架？

Lingo.dev Compiler 目前支持以下 React 框架：

  • Next.js（仅支持 App Router）
  • React Router v6+
  • Remix（最新版本）
  • Vite + React

我们欢迎对其他平台实现编译器支持感兴趣的贡献者。欢迎加入我们的 Discord 社区 讨论实现策略。

我可以添加更多语言吗？

可以！您可以通过在编译器配置中直接配置自定义模型来扩展语言支持：

const compilerConfig = {
  sourceLocale: "en",
  targetLocales: ["es", "fr", "de", "pt", "it"],
  models: {
    "*:pt": "mistral-saba-24b",
    "en:it": "meta-llama/llama-4-maverick-17b-128e-instruct",
    "*:*": "mistral-saba-24b",
  },
};

lingoCompiler.next(compilerConfig)(nextConfig);

请参阅 高级配置 了解详细信息。

我可以使用自定义提示吗？

是的！您可以直接在编译器配置中自定义翻译提示：

const compilerConfig = {
  sourceLocale: "en",
  targetLocales: ["es", "fr", "de"],
  prompt:
    "You are a professional translator specializing in technical documentation. Translate from {SOURCE_LOCALE} to {TARGET_LOCALE} while maintaining technical accuracy.",
};

对于自定义术语表，请在提示中包含术语定义。参考我们的默认提示以获取最佳实践。

我可以使用更多的 LLM 提供商吗？

目前，Lingo.dev 编译器集成了 GROQ，但我们希望很快支持更多的 LLM 提供商（联系我们或发送拉取请求！）。

我需要在 CI/CD 中使用 GROQ API 密钥吗？

通常不需要。如果您在本地构建应用程序，所有翻译将存储在 lingo/ 目录中。您的 CI/CD 构建将不需要调用 LLM 来翻译任何字符串。

或者，您可以将 GROQ_API_KEY 变量添加到您的 CI/CD 中，并在构建时完成所有翻译，但我们不推荐这种方法，以便更好地控制最终翻译。

我可以编辑翻译吗？

可以！您可以手动编辑 lingo/dictionary.js 文件。它导出一个包含所有文件和条目翻译的对象。您可以在 content 属性中编辑每种语言的文本。您的编辑将被保留，直到 React 组件中的源文本被更新。

不喜欢编辑 JavaScript 对象？ 我们即将发布编辑器以改善编辑体验。如果您感兴趣，请告诉我们！

我如何重新翻译整个应用程序、特定文件或语言？

要重新翻译整个应用程序，请从 lingo/ 目录中删除 dictionary.js 文件。

要仅重新翻译特定文件，您可以从 dictionary.js 中删除它们的键（文件名）。

如果您想重新翻译特定语言，您需要删除该语言的所有记录。

为什么我需要在本地构建应用程序？

本地构建通过以下方式规范化您的 lingo/ 翻译文件：

  • 删除未使用的翻译键
  • 更新内容指纹
  • 确保文件格式一致
  • 为生产部署优化

在提交更改之前，请始终运行 npm run build 以保持翻译文件的整洁。

缺少翻译！

如果缺少翻译：

  1. 在本地构建以规范化您的 lingo/ 文件：

    npm run build

  2. 检查您的 API 密钥是否正确设置：

    # 确保您的 .env 文件包含以下内容
GROQ_API_KEY=gsk_...

  3. 提交更新的文件：

    git add lingo/
git commit -m "更新翻译"

  4. 在更改后重启开发服务器。

我可以设置自定义术语表吗？

可以！使用自定义提示直接在编译器配置中定义术语和术语表：

const compilerConfig = {
  sourceLocale: "en",
  targetLocales: ["es", "fr", "de"],
  prompt:
    "您是一名专业翻译，请一致使用以下术语：'Dashboard' 在法语中应为 'Tableau de bord'，'Settings' 在西班牙语中应为 'Configuración'。从 {SOURCE_LOCALE} 翻译到 {TARGET_LOCALE}。",
};

我如何跳过某些内容的翻译？

使用 data-lingo-skip 属性：

<div data-lingo-skip>此内容将不会被翻译</div>

根据内容类型进行条件跳过：

<code data-lingo-skip>// 代码块会自动跳过 const apiKey = "secret-key";</code>

我可以覆盖特定的翻译吗？

可以！使用 data-lingo-override- 属性进行特定语言的覆盖：

<button data-lingo-override-es="¡Hola!" data-lingo-override-fr="Bonjour!">
  Hello
</button>

这在以下情况下非常有用：

  • 不应翻译的品牌名称
  • 特定地区的术语
  • 需要人工审核的营销文案

编译器如何处理复数形式？

编译器会自动处理基本的复数模式，但对于复杂的复数规则，您可能需要相应地构建您的 JSX：

// 编译器会正确处理此内容
<p>{count === 1 ? "1 item" : `${count} items`}</p>

生产环境中的性能如何？

Lingo.dev 编译器针对生产环境进行了优化：

  • 零运行时成本 - 翻译在预编译阶段完成
  • 包分割 - 仅加载活动语言环境
  • Tree shaking - 未使用的翻译会被移除
  • CDN 友好 - 静态翻译文件高效缓存

我可以在 TypeScript 中使用它吗？

可以！编译器可以无缝集成到 TypeScript 项目中。所有提供的 React 组件都完全支持类型：

import { LocaleSwitcher } from "lingo.dev/react/client";

// 完全支持 TypeScript
const locales: string[] = ["en", "es", "fr"];
<LocaleSwitcher locales={locales} />;

我如何报告错误或请求新功能？

下一步