locli

@locli/cli

将应用面向用户的文本放入 locli：推送新文本，让项目所有者批准发布，然后拉取已批准的翻译。专为编码 Agent 打造，适用于任何技术栈：iOS String Catalogs、Android strings.xml，以及适用于 Web 和后端的 JSON。需要 Node 18+，无依赖。

npx @locli/cli init

init 会检测你的文本文件并写入：

• locli.json，包含项目 slug、源语言，以及每个目录对应的一种目标语言
• 在 AGENTS.md 中写入 locli 区块（如果已有 CLAUDE.md，还会在其中写入 @AGENTS.md）
• 将 locli Agent 技能写入 .agents/skills/locli/（并从 .claude/skills/locli/ 链接过去）

登录后，init 还会创建项目并设置其语言和平台。可以安全地重复运行。

登录

npx @locli/cli login

login 会打开浏览器。登录或创建免费账户，然后批准 CLI。令牌按服务器分别存储在 ~/.config/locli/credentials.json 中，只有你本人可以读取。在 CI 中，改为设置 LOCLI_TOKEN。whoami 会显示账户；logout 会撤销令牌。

工作流

1. 在源语言文件中添加新键，例如 receipt_import_title，并附上注释。
2. npx @locli/cli push 只会上传 locli 中尚不存在的内容。它不会覆盖已有文本。来自 Git 功能分支的新键会归为一个功能。
3. 项目所有者在 locli Web 应用中批准发布。
4. npx @locli/cli pull 会将最新获批的发布写入你的文件。

locli.json

{
  "project": "example-app",
  "sourceLanguage": "en",
  "targets": [
    { "platform": "ios", "format": "xcstrings", "path": "App/Localizable.xcstrings" },
    { "platform": "android", "format": "android-xml", "path": "app/src/main/res" },
    { "platform": "web", "format": "json", "path": "messages/{locale}.json" }
  ]
}

每个目标都包含 platform（ios、android、web 或 backend）、format 和 path。路径相对于 locli.json。

• Android 目标可选填 file；默认值为 strings.xml。
• JSON 目标的路径中必须包含 {locale}，并可选填 keyPrefix。
• apiURL 为可选项；默认值为 https://locli.dev。

JSON schema 随 @locli/cli/schema/locli.json 一同发布。

命令

命令	效果
login [--no-browser] / logout / whoami [--json]	在浏览器中批准 CLI；撤销令牌；显示账户
init [--name] [--slug] [--source LANG] [--target platform:format:path]… [--yes] [--no-agent-files]	检测目录、写入配置和 Agent 文件、创建项目
push [--dry-run] [--branch B] [--target platform]	上传缺失的键和值；不会覆盖现有内容
pull [--draft] [--release NAME] [--target platform]	写入最新获批的发布（或指定发布）
status [--json]	显示语言、缺失的翻译、未关闭的功能、尚未发布的更改和术语表问题
areas [--feature NAME] [--json]	列出功能区域，或查找新功能文本所属的区域
guide [--json] [--set FILE]	显示翻译指南（语气、术语表）以及不符合指南的文本；--set 会替换指南
mcp	通过 stdio 启动 MCP 服务

每条命令都支持 --api-url、--config 和 --help。退出代码：0 表示成功，1 表示错误，2 表示用法错误。

环境变量：

• LOCLI_TOKEN：CI 中使用的 API 令牌。
• LOCLI_API_URL：服务器地址。
• LOCLI_CONFIG：locli.json 的路径。
• LOCLI_BRANCH：覆盖检测到的分支。

MCP 服务

MCP 服务提供七种工具：

• locli_status
• locli_areas
• locli_guide
• locli_find_texts
• locli_add_texts
• locli_push
• locli_pull

Claude Code：安装插件（包含技能和 MCP 服务），或仅添加 MCP 服务：

/plugin marketplace add mariohahn/locli
/plugin install locli@locli
claude mcp add --scope project locli -- npx -y @locli/cli mcp

Cursor（.cursor/mcp.json）和其他使用 mcpServers 的客户端：

{ "mcpServers": { "locli": { "command": "npx", "args": ["-y", "@locli/cli", "mcp"] } } }

Codex（~/.codex/config.toml）：

[mcp_servers.locli]
command = "npx"
args = ["-y", "@locli/cli", "mcp"]

已知限制

• Android 中带有标记（<b>、<a> …）的字符串会在推送时跳过，拉取时保持原样。
• JSON：只有位于 count 或 argN 上的顶层 ICU 复数才会成为复数键。其他 ICU 消息会作为纯文本推送。
• JSON：非字符串值会跳过并显示警告。

Agent 指南：https://locli.dev/docs/agents.md · 许可证：MIT