快速入门
Lingo.dev CLI 的核心优势在于通过单个 CLI 命令高效地将应用程序和 Markdown 内容本地化为目标语言。
本快速入门指南假设您即将使您的应用程序支持多语言，或者已经配置了支持两种或更多语言的功能。因此，本指南设计得足够简短，可以在 10 分钟内完成，但又足够详细以便理解其内部工作原理。
完成本指南后，您将能够：
- 使用 AI 翻译引擎将应用内容本地化为西班牙语和日语；
- 理解源文件、目标文件和配置如何协同工作；
- 设置一个本地化工作流，使您的应用程序和 Markdown 内容能够扩展到数十种语言和数万字。
让我们开始吧！
前置条件
Markdown
Markdown 文件是结构化文档，这意味着无需进行任何预先设置。Lingo.dev CLI 可以直接处理 .md 文件，在本地化内容的同时保持格式，因此您可以直接进入 步骤 1。
应用程序
要使应用程序支持多语言，现代 Web 和移动应用程序需要开发人员首先设置国际化 (i18n) 配置。
在本快速入门中，我们将创建一个独立的 JSON 文件，演示 Lingo.dev CLI 如何本地化应用程序内容。
在与您的实际应用程序集成时，请参考我们推荐的框架指南：
- React：react-intl
- Vue：vue-i18n
- Svelte：svelte-i18n
- Angular：ngx-translate
- iOS：Localizable.xcstrings
- Android：strings.xml
步骤 1：初始化项目
Lingo.dev CLI 使用标准的 i18n.json 配置文件来声明您的本地化设置。要以交互方式创建它，请运行：
bash npx lingo.dev@latest init
它会询问您有关项目的问题，然后在项目根目录中创建一个 `i18n.json` 文件。
文件内容应如下所示：
```json
{
"locale": {
"source": "en",
"targets": ["es", "ja"]
},
"buckets": {
"json": {
"include": ["locales/[locale].json"]
}
}
}
让我们逐一解析每个配置元素：
-
locale.source— 您的团队编写内容所使用的语言。此设置标识哪些文件包含权威内容。所有本地化流程都从源语言流向目标语言。 -
locale.targets— 一个 ISO 639-1 语言代码数组，表示您的目标市场。每个代码对应一个单独的文件（或文件中的一个部分，具体取决于格式）。您可以从一种或两种语言开始，随着扩展添加更多语言。 -
buckets.json.include— 类似 Glob 的模式，告诉 CLI 在哪里查找和创建语言文件。特殊的[locale]标记会扩展为每种语言代码。使用模式locales/[locale].json，CLI 会查找locales/en.json作为源文件，并生成locales/es.json和locales/ja.json作为目标文件。您可以指定多个模式，甚至在单个配置中混合使用多种格式。
随着项目的增长，您将发现以下高级功能：
- 针对不同文件类型或应用程序部分的多个存储桶
exclude模式以跳过某些文件lockedKeys用于防止特定值被翻译
创建英文源文件
在本快速入门中，我们将创建一个语言环境文件：
mkdir -p locales
echo '{"greeting":"Hello, world!","button.submit":"Submit"}' > locales/en.json
这将创建一个 locales 目录和一个包含两个翻译键的英文源文件。像 greeting 这样的键适用于扁平结构，而像 button.submit 这样的命名空间键有助于组织更大的应用程序。
嵌套对象也被支持。您可以在其余文档中找到有关不同文件格式的更多详细信息。
第 2 步. 身份验证
Lingo.dev CLI 将您的内容发送到 AI 翻译引擎进行本地化，因此我们需要先进行身份验证。
选项 1. 原始 LLM API 访问
Lingo.dev CLI 帮助您使用 LLM 模型（如 OpenAI 或 Anthropic）进行本地化和翻译。
这意味着您将按处理的令牌计费，您可以控制模型选择、系统提示和所有模型参数。
要进行身份验证，请在项目根目录中创建一个 .env 文件并添加您的 API 密钥：
# 如果您使用的是 OpenAI
OPENAI_API_KEY=sk-...
# 如果您使用的是 Anthropic
ANTHROPIC_API_KEY=sk-...
或者，您可以在当前 shell 会话中导出变量，而不是使用 .env 文件：
export ANTHROPIC_API_KEY=sk-ant-...
想为其他提供商添加支持？Lingo.dev CLI 是开源的，欢迎贡献！Fork 此存储库并提交拉取请求：github.com/lingodotdev/lingo.dev。
选项 2. Lingo.dev Engine
或者，您可以创建一个免费的 Lingo.dev Engine 账户，并将其用作您的 AI 翻译引擎。
它提供动态模型选择、针对每种语言对的自动路由、自动模型回退、考虑过去翻译的翻译记忆，以及支持您项目领域特定术语的术语表。提供免费和付费选项，免费 Hobby 计划应该足以完成本教程。
要进行身份验证，请运行：
npx lingo.dev@latest login
重要细节。 如果您使用的是 Brave 浏览器，或者您的浏览器扩展阻止了身份验证流程，您可以通过在 .env 文件中添加 LINGODOTDEV_API_TOKEN 环境变量手动进行身份验证：
LINGODOTDEV_API_TOKEN=...
您可以在 Lingo.dev Engine 项目设置中找到该令牌。
第 3 步：设置 AI 翻译引擎
现在您已完成身份验证，接下来需要配置要使用的 AI 翻译引擎。
选项 1：原始 LLM API 访问
要使用 OpenAI，请更新您的 i18n.json 配置以使用 openai 提供程序：
{
"locale": {
"source": "en",
"targets": ["es", "ja"]
},
"buckets": {
"json": {
"include": ["locales/[locale].json"]
}
},
"provider": {
"id": "openai",
"model": "gpt-4o-mini",
"prompt": "Act as a professional software localization expert. Translate each key from {source} to {target}. Preserve ICU message format placeholders like {name} and {{count}}. Maintain Markdown formatting including links and code blocks. Match the tone and formality of the source text. Technical terms that are typically untranslated in the industry should remain in English."
}
}
您可以尝试不同的提示词以自定义本地化行为，但我们发现以上提示是一个不错的起点！
provider 配置控制直接的 LLM 访问：
id— 可以是openai或anthropicmodel— 使用的具体模型版本。例如：gpt-4o-mini、gpt-4o（OpenAI），或claude-3-haiku、claude-3-sonnet（Anthropic）。prompt— 指导翻译行为的系统提示。{source}和{target}占位符将在运行时替换为实际的语言代码。此提示是您强制术语、风格和领域特定规则的机会。
选项 2：Lingo.dev 引擎
如果您使用 Lingo.dev 引擎 作为 AI 翻译引擎，可以完全跳过 provider 节点。
该引擎会根据 Lingo.dev 团队的研究和引擎设置自动选择模型和提示。
您的 i18n.json 配置：
{
"locale": {
"source": "en",
"targets": ["es", "ja"]
},
"buckets": {
"json": {
"include": ["locales/[locale].json"]
}
}
}
注意：使用 Lingo.dev 引擎时，请完全省略 provider 节点。引擎会自动选择模型和提示。
第 4 步. 翻译
要本地化您的应用程序，请运行：
npx lingo.dev@latest i18n
CLI 将创建目标文件，并更新用于跟踪内容指纹的 i18n.lock 文件。这确保了后续运行时的增量更新。
现在，您的应用内容已经完成本地化！
下一步
您已完成核心本地化工作流程。您的代码库现在包含了本地化文件，可以像其他代码工件一样进行提交、审查和部署。
接下来，您可以：