用编程智能体完成设置

让 Claude Code、Codex 或 Cursor 借助 CLI 的智能体指南,在你的项目中设置 Lingo.dev:可直接复制的提示词、AGENTS.md 配置块、lingo agent setup 和 lingo agent-guide。

CLI 内置了面向 Claude Code、Codex 和 Cursor 等编程智能体的指南。将下方任一提示词交给你的智能体,它就会运行 lingo agent-guide,阅读对应任务的指南,再通过 CLI 在你的代码仓库中完成操作。引擎词汇表、GitHub App 连接等账户相关操作则通过 Lingo.dev MCP server 完成。

指南随 CLI 一起提供,因此智能体读取的指南始终与当前运行的 CLI 版本一致。翻译任何内容前,智能体都会先展示计划和预估,等待你批准后再继续。

提示词 #

从项目根目录启动智能体,然后粘贴提示词。

从零开始设置 Lingo.dev #

text
Set up Lingo.dev localization in this project. Run npx @lingo.dev/cli@latest agent-guide setup and follow it.

智能体会:

  1. 检查是否已配备 Lingo.dev MCP 工具。如果没有,会添加服务器,并请你重启智能体,再次粘贴提示词。
  2. 识别技术栈,找出应用加载的所有源文件,并执行对应技术栈的指南(Rails、iOS、Android、Markdoc、电子邮件、i18n 库或文档网站)。
  3. 请你登录。收到提示后,请在自己的终端中运行 npx @lingo.dev/cli@latest login;切勿将 API 密钥粘贴到对话中。
  4. 运行 lingo init 和 lingo link。如果项目已有翻译,会检查占位符损坏、文本未翻译和术语不一致等问题,并只修复你同意修复的内容。
  5. 展示计划和 lingo push --estimate,待你批准后开始翻译。
  6. 在应用中注册新的语言区域,并询问你是否要连接 GitHub App。

连接 GitHub App #

text
Connect the Lingo.dev GitHub App to this repository. Run npx @lingo.dev/cli@latest agent-guide github and follow it.

如果项目尚未完成设置,智能体会先完成设置,再检查 GitHub App 是否有权访问代码仓库;如果没有,会提供链接,让你解决访问问题。接着,你可以选择让 GitHub App 在合并后还是在拉取请求中执行翻译。只有在你同意后,智能体才会创建包含配置的拉取请求。

AGENTS.md 配置块 #

lingo init 和 lingo agent setup 会在项目根目录的 AGENTS.md 中写入一段简短的配置块,让后续每次智能体会话都知道:开展本地化工作前,应先阅读指南。

markdown
<!-- lingo:begin -->

## Lingo.dev localization

This project is localized with Lingo.dev. The config is `.lingo/config.json` next to this file. Lingo.dev commands and workflows change between versions, so do not rely on what you remember about them.

Before any localization task (translating content, adding a locale, connecting GitHub, changing the glossary or tone of voice), run `npx @lingo.dev/cli agent-guide` from this directory and follow the guide it names. The guides ship with the CLI and describe the version you run.

This block is written by `lingo init` and `lingo agent setup`. Text between the markers is replaced on the next run; keep your own notes outside them.

<!-- lingo:end -->
  • 如果 AGENTS.md 不存在,会自动创建。标记之外的文本会保留,后续运行只会替换标记之间的文本。
  • 已有的 CLAUDE.md 也会写入此配置块,除非它导入的 AGENTS.md 已包含该配置块(@AGENTS.md)。不会创建 CLAUDE.md。
  • 如果文件无法读取、链接指向项目之外,或标记不成对,会保留文件原样并发出警告。修复文件后,请再次运行 lingo agent setup。
  • 如需跳过配置块,请运行 lingo init --no-agents-md。

当智能体在项目中运行 Lingo.dev 命令,而项目的 AGENTS.md 或 CLAUDE.md 中没有配置块时,CLI 会向 stderr 输出一行提示,让智能体运行 lingo agent setup -y。用户和 CI 都不会看到这条提示。

lingo agent setup #

bash
lingo agent setup

检查本机上的编程智能体(Claude Code、Codex 和 Cursor,以及当前运行此命令的智能体)是否已配置 Lingo.dev MCP server,并逐一指出未配置的智能体需要修改哪个配置文件。此命令不会编辑智能体配置;请按照 MCP 设置 中的步骤添加服务器。在项目中运行时,它还会先征求你的同意,再写入 AGENTS.md 配置块。

选项作用
--client <name>仅检查指定的智能体,即使未检测到它:claude-code、codex 或 cursor。可重复指定。
--dry-run预览将要进行的更改,不写入任何内容。
--status显示检测到的智能体已完成哪些设置。忽略 --client。
-y, --yes不再询问,直接写入配置块。

如果没有可检查的智能体,命令会失败,不写入任何内容。

lingo agent-guide #

bash
lingo agent-guide           # the agent guide and the list of guides
lingo agent-guide setup     # one guide

未指定名称时,会输出所有智能体最先使用的入门指南(CLI 或 MCP、登录、尚未完成的入门设置),并列出指南列表。指定名称时,会输出对应的指南。名称无法识别时,会以退出码 1 退出,并列出当前版本可用的指南。lingo guide 为使用 @lingo.dev/react 的用户提供这些指南。

无人值守会话 #

在云端或 CI 会话中,设置 LINGO_API_KEY 即可让智能体无需登录。这类智能体会完成任务中通过 CLI 执行的部分,但不会设置 MCP server。最后一条消息会列出仍需通过账户完成的操作,你可以在网页应用中完成,也可以交给已配置 MCP server 的智能体。

如果翻译因计费原因被拒绝,CLI 会在需要人工处理时(额度耗尽、达到引擎上限或套餐缺少所需功能)以退出码 9 退出;如果每日令牌额度已用尽,则以退出码 75 退出。同时会输出原因和计费页面链接。指南会要求智能体遇到任一退出码时停止。

智能体报告 #

指南会要求智能体在步骤失败时和任务结束时,通过 lingo agent report 向 Lingo.dev 发送一份简短报告,帮助我们改进指南。报告包含指南和步骤、一两句话的摘要、智能体名称,以及关联的组织和引擎。CLI 会移除凭据和机密值,并将每段文本截断至 500 个字符。报告不会导致任务失败;如果无人登录或遥测已关闭(LINGO_TELEMETRY_DISABLED=1、DO_NOT_TRACK=1 或 OTEL_SDK_DISABLED=true),则不会发送任何内容。