Localize Anything

面向 Coding Agent 的本地化专业能力层。
_{An agent-native localization workflow and review layer.}

简体中文 · English

你已经让 Coding Agent 帮你写代码了。现在让它为项目增加俄语支持——它能翻，但翻完之后呢？术语是否一致、关键概念有没有译对、几百条译文怎么审查——这些问题 Agent 单靠自己解决不了。

Localize Anything 给它一套专业本地化流程： 扫描范围、建立项目术语表、系统审查所有译文、把需要你亲自确认的高风险项压缩到个位数。它不是一个翻译工具，也不是又一个 CI 平台——它是嵌入 Agent 工作流的本地化专业层，让项目记忆跨会话复用，让审查从「逐条看」变成「只看那几条真正需要你决定的」。

工作流

localize scan
→ localize glossary bootstrap
→ Coding Agent 本地化（项目原生 build/test）
→ localize check
→ localize review
→ 人工确认
→ localize report

Localize Anything 不替代 Coding Agent、项目构建系统、Git 或人工产品判断。它负责范围、Project Memory、Glossary、确定性检查、独立审查和少量高风险确认。

Anything 的边界

这里的 "Anything" 不是自动翻译并改写任何文件。它表示：发现项目里的本地化表面，解释哪些已经扫描、哪些能由可靠 adapter 处理、哪些需要先改项目结构或源码、哪些属于动态内容/非文本资产/暂不支持范围，并把这些限制写进报告。

比如 JSON locale 通过检查，不等于整个 React 应用已经完整本地化；.strings 或 .xcstrings 通过检查，不等于整个 iOS/Swift 项目已经覆盖；build 通过，也不等于所有可见 UI 都被启动和视觉验证。

快速上手

需要 Python 3.11+：

git clone https://github.com/xueyang-dev/localize-anything.git
cd localize-anything
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[yaml]"

对目标项目声明一次本地化任务，建立 Project Memory：

如果项目还没有任何 i18n，Coding Agent 必须先按项目原生方式建立最小 i18n，并创建源语言资源文件。不要在 --source 文件存在前运行 localize scan；scan 只记录已经存在的 source resource，不负责创建它。

localize scan /path/to/project \
  --source-locale en \
  --target-locale ru \
  --source locales/en.json

生成 canonical Glossary：

localize glossary bootstrap /path/to/project

接下来 Coding Agent 修改应用代码与目标语言资源，并运行项目自己的验证（npm test、npm run build、git diff 等）。工程修改完成后：

localize check /path/to/project --target locales/ru.json
localize review /path/to/project --target locales/ru.json

如果声明了多个 source，必须按 scan 顺序为每个 source 传一个 --target。check 和 review 会输出 source_target_mapping，并拒绝数量不一致、明显把 source locale 当 target、adapter 不一致，以及清晰的路径形状矛盾。

把 .localize-anything/review-packet.json 交给一个未参与生成译文的独立 Agent context 审查，导入审查结果并生成报告：

localize review /path/to/project --target locales/ru.json --findings review.json
localize report /path/to/project

check、review、report 和 Skill 统一使用这四个 severity：blocking、actionable、coverage_limitation、informational。自动放行的检查项写入 review_items；只有真实问题写入 findings。

最小 review.json：

{
  "reviewer": "fresh-review-context",
  "review_items": [
    {
      "id": "checked-placeholders",
      "severity": "informational",
      "status": "auto_cleared",
      "note": "Placeholders were checked and no issue was found."
    }
  ],
  "findings": [
    {
      "id": "brand-name",
      "severity": "actionable",
      "status": "needs_human_confirmation",
      "note": "Confirm whether the product name remains untranslated."
    }
  ]
}

只有状态为 needs_human_confirmation 的开放 finding 可以接受人工确认：

localize report /path/to/project --confirm confirmations.json

所有核心状态保存在目标项目的 .localize-anything/ 目录，可随 Git 提交与共享。

Review Packet 字段

.localize-anything/review-packet.json 是交给独立 review context 的自包含输入：

• instruction：审查任务和独立性要求。
• project_memory：声明的语言、source 文件、风格、保留规则、翻译记忆和已确认决策。
• glossary：canonical concept；锁定译名用 status: "locked" 和 target.preferred，保留源词用 behavior: "preserve" 加 status: "locked"。
• deterministic_check：最近一次结构检查结果，或 null。
• source_target_mapping：按 scan 顺序列出的 source→target 文件映射。
• files：已经对齐的 source/target segments。
• review_result_format：独立 reviewer 应返回的 JSON 形状。

让 Coding Agent 使用

主入口是 Agent Skill，CLI 是它的确定性工具。

• Codex：把仓库的 skills/localize-anything/ 目录作为可用 Skill（或复制到你的 Codex skills 目录），然后直接提出：

  使用 Localize Anything，为这个项目增加俄语支持。

• Claude Code：把同一目录放入项目的 .claude/skills/localize-anything/（保留 SKILL.md 和 references/），使用同样的自然语言请求即可。

Skill 只指导流程；代码修改、资源编辑、build/test 和 Git 操作仍由 Coding Agent 使用项目原生命令完成。

两种工作深度

深度	适用场景	内容
Standard	日常新增语言、更新文案	范围、Glossary、Agent 实施、确定性检查、独立 Review、高风险确认
Release	正式发布	Standard 全部内容 + 页面截图、页面级 Review、项目原生 build/test、locale 切换/持久化/检测/fallback 验证、干净 Git diff、发布证据

职责边界

角色	职责
Localize Anything Skill	范围、Glossary、Project Memory、流程、独立 Review、风险汇总
localize CLI	扫描、结构检查、review packet、finding/confirmation 约束、报告
Coding Agent	i18n 架构、代码和资源修改、语言切换、fallback、build/test、截图、Git
用户	产品含义、品牌、正式术语、高风险歧义和发布判断

确定性检查不证明译文自然或语义正确，独立 Agent Review 也不等于人工发布批准。ready 只表示当前声明范围内的核心检查、Review 和确认已完成，不替代项目原生 build/test、截图或 Git Review。

开发验证

python -m unittest discover -s tests -p 'test_*.py'
python -m compileall -q runtime tests

协议和 adapter manifest 使用仓库内的 dependency-free validator：

from pathlib import Path
from runtime.localize_anything.contracts import validate_adapter_tree
from runtime.localize_anything.schema_validation import validate_protocol_tree

assert validate_protocol_tree(Path("protocol"))["status"] == "pass"
assert validate_adapter_tree(Path("adapters"))["status"] == "pass"

文档

• 产品方向 — 定位与范围基准，一切文档的源头
• 当前架构
• 架构路线图
• 格式处理边界 — 核心格式与受限兼容方向的完整说明
• 核心数据契约
• Agent Skill
• 迁移说明 — 从旧平台迁移到五命令核心
• 0.5.1 发布说明

历史 v0.4 平台设计仅保留在 Legacy Architecture Snapshot 与 Git 历史中。

非目标

Localize Anything 不是：

• 翻译模型或 Provider 平台；
• 企业 TMS；
• 通用多 Agent orchestration framework；
• Workbench 或发布治理系统；
• Git、CI 或项目构建系统的替代品；
• 自动改写所有源码字符串或资产的工具；
• 因检测到 Swift、Android、React、DOCX 等技术栈就宣称完整支持的工具；
• 「零源语言字符」或专业翻译质量的自动认证。

License

MIT