让编程智能体帮你完成设置
CLI 自带专为 Claude Code、Codex 和 Cursor 等编程智能体编写的指南。把下方任意一条提示词交给你的智能体,它就会运行 lingo agent-guide,阅读对应任务的指南,再通过 CLI 在你的代码仓库中完成工作。账号相关操作,例如引擎术语表的管理或 GitHub App 的连接,则通过 Lingo.dev MCP server 完成。
指南随 CLI 一起提供,因此智能体读取的指南始终与它运行的 CLI 版本一致。在翻译任何内容之前,智能体会先向你展示计划和预估,并等待你批准。
提示词 #
在项目根目录下,将一条提示词粘贴到你的智能体中。
从零开始设置 Lingo.dev #
Set up Lingo.dev localization in this project. Run npx @lingo.dev/cli@latest agent-guide setup and follow it.智能体会:
- 检查是否已配置 Lingo.dev MCP 工具。如果没有,它会添加服务器,并请你重启智能体,再次粘贴提示词。云端或 CI 智能体会跳过这一步和浏览器登录;请参阅无人值守会话。
- 识别技术栈,找出应用加载的所有源文件,并按照对应技术栈的指南操作(Rails、iOS、Android、Markdoc、电子邮件、i18n 库或文档网站)。
- 请你登录。收到提示时,请在你自己的终端中运行
npx @lingo.dev/cli@latest login;切勿将 API 密钥粘贴到对话中。 - 运行
lingo init和lingo link。如果项目已有翻译,它会检查占位符损坏、文本未翻译和术语不一致等问题,并且只修复你同意修改的内容。 - 向你展示计划和
lingo push --estimate,经你批准后再开始翻译。 - 在应用中注册新的语言区域,并询问你是否要连接 GitHub App。
连接 GitHub App #
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 中写入一小段文本,让后续每次智能体会话都知道:开始本地化工作前,要先阅读指南:
<!-- 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;如果未检测到你的智能体,请加上--client <name>。 - 如需跳过该文本块,请运行
lingo init --no-agents-md。
当智能体在项目中运行 Lingo.dev 命令,而该项目的 AGENTS.md 或 CLAUDE.md 中没有文本块时,CLI 会向 stderr 输出一行提示,告知智能体运行 lingo agent setup -y。用户和 CI 不会看到这条提示。
lingo agent setup #
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 | 直接写入文本块,无需询问。 |
未使用 --status 时,如果没有可检查的智能体,命令会失败,且不会写入任何内容。因此,请使用 --client 指定一个智能体。
lingo agent-guide #
lingo agent-guide # the agent guide and the list of guides
lingo agent-guide setup # one guide不指定名称时,它会输出每个智能体都要先阅读的入门指南(CLI 或 MCP、登录、尚未完成的初始设置),并列出所有指南。指定名称时,它会输出对应的指南。如果名称未知,命令会以退出码 1 退出,并列出当前版本可用的指南。使用 @lingo.dev/react 的用户可在 lingo guide 下找到专为用户编写的指南。
无人值守会话 #
在云端或 CI 会话中,设置 LINGO_API_KEY 即可让智能体无需登录。这类智能体会处理任务中的 CLI 部分,但不会设置 MCP server。它的最后一条消息会列出尚未完成、需要账号才能处理的任务;你可以在网页应用中完成这些任务,也可以交给已配置 MCP server 的智能体。
当翻译因计费问题被拒绝时,如果需要用户处理(额度耗尽、达到引擎上限或缺少套餐功能),CLI 会以退出码 9 退出;如果当天的 token 配额已用完,则以退出码 75 退出。它会输出原因和计费页面链接。指南要求智能体遇到这两个退出码中的任意一个时停止操作。
智能体报告 #
指南要求智能体在步骤失败时以及任务结束时,通过 lingo agent report 向 Lingo.dev 发送简短报告,帮助我们改进指南。报告包含指南和步骤、一到两句话的摘要、智能体提出的方案、智能体名称,以及关联的组织和引擎。CLI 会移除摘要和方案中的凭据及机密值,并将两者分别截断至 500 个字符;指南要求智能体在所有字段中都不要包含代码、文件内容或机密信息。报告不会导致任务失败。如果无人登录,或遥测已关闭(LINGO_TELEMETRY_DISABLED=1、DO_NOT_TRACK=1 或 OTEL_SDK_DISABLED=true),则不会发送任何内容。