page-agent 多语言 i18n 架构解析：自然语言网页 Agent 的 UI 文案与系统提示词国际化全指南
page-agent 多语言 i18n 架构解析自然语言网页 Agent 的 UI 文案与系统提示词国际化全指南【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agentpage-agent是一个用 JavaScript 实现的页内 GUI Agent能用自然语言直接控制网页界面。它的国际化i18n方案覆盖三层UI 文案、扩展元数据和系统提示词——本文带你完整看懂这套多语言架构是如何运作的。项目速览一个「会操作网页的 AI」page-agent 的核心思路是让 AI 像人一样点击按钮、填写表单、滚动页面。为了让中文用户获得母语级的体验项目在三个不同层面分别做了本地化处理三者互不耦合、各司其职层面作用对象实现位置UI 文案层控制面板的状态、工具动作、错误提示packages/ui/src/i18n/扩展元数据层Chrome 商店展示的名称、描述packages/extension/public/_locales/系统提示词层发送给大模型的 system promptpackages/core/src/项目整体结构可从 README.md 与 docs/README-zh.md 快速了解多语言正是其中用户体验的关键一环。UI 文案层类型安全的 I18n 引擎这是最核心的一层位于 packages/ui/src/i18n/index.ts。1. 一个极简的 I18n 类整个引擎只有约 50 行t(key, params?)按点路径如ui.panel.stop从翻译表中取值支持{{param}}占位符插值见 index.ts#L36-L41容错回退找不到 key 时打印警告并原样返回 key而不是让界面崩溃默认语言未识别的语言自动回退到en-US见 index.ts#L13-L162. 让 TypeScript 帮你「查字典」真正的亮点在 packages/ui/src/i18n/locales.ts英文是基准语言en-US是结构参考zh-CN必须与其结构完全一致见 locales.ts#L49 的注释约定类型从结构自动生成通过DeepStringify把英文对象转成字符串类型locales.ts#L98-L102再用NestedKeyOf递归提取所有合法 key 路径locales.ts#L105-L112这意味着调用i18n.t(ui.panel.stop)时key 写错、中文漏翻译某个字段编译阶段就会报错——多语言一致性由类型系统兜底而不是靠人肉核对。3. 文案如何被消费控制面板 Panel.ts 在构造时通过配置项创建 I18n 实例Panel.ts#L65-L68之后所有界面文本都走t()状态文案「准备就绪 / Ready」Panel.ts#L240实时动作描述ui.tools.clicking传入index参数渲染「正在点击元素 [12]...」Panel.ts#L281-L295工具结果与错误提示如「未找到索引为 5 的交互元素」语言选择入口则定义在 Panel.ts#L11-L18 的PanelConfig.language而合法语言值由 packages/core/src/types.ts#L7-L11 中的SupportedLanguage类型统一约束——目前支持en-US与zh-CN。扩展元数据层Chrome 官方的 _locales 机制浏览器扩展的名称和描述由 Chrome 本身渲染无法用 JS 修改因此 page-agent 遵循 Manifest V3 的官方规范在两个目录下放置静态翻译文件英文packages/extension/public/_locales/en/messages.json中文packages/extension/public/_locales/zh_CN/messages.json两个文件都只包含 3 个 keyextName、extDescription、extActionTitle例如中文版将扩展描述本地化为「AI 驱动的浏览器自动化助手用自然语言控制网页。」扩展打包时Chrome 会根据浏览器语言自动选取对应目录——零 JavaScript 代码完全依赖平台能力。系统提示词层一行正则切换 AI 的工作语言UI 说的是「人话」而 Agent 的「思维语言」由系统提示词决定模板见 packages/core/src/prompts/system_prompt.md。其中专门有一段language_settings - Default working language: **English** - Use the language that user is using. Return in users language. /language_settings动态替换发生在 PageAgentCore.ts#L475-L487 的#getSystemPrompt()中若用户配置了customSystemPrompt直接返回尊重完全自定义否则根据config.language判断目标语言zh-CN→ 「中文」其余 → 「English」用正则把模板里的默认工作语言整段替换掉PageAgentCore.ts#L481-L484这种「模板保持英文 运行时定点替换」的做法非常轻巧只维护一份提示词却能保证 AI 的推理输出与用户的语言一致——这正是自然语言 Agent 体验自然感的关键。官网的语言检测浏览器偏好自动生效项目官网packages/website/的语言方案则采用了 React Context见 packages/website/src/i18n/context.tsx首次访问读取localStorage其次用navigator.language判断浏览器是否以zh开头context.tsx#L12-L16手动切换语言后会持久化刷新不丢失context.tsx#L18-L21通过useLanguage()Hook 向全站组件提供language/isZh/setLanguage配合 packages/website/src/components/LanguageSwitcher.tsx 实现一键切换如果你想新增一种语言改这几处就够了UI 层在 locales.ts 中新增语言对象结构与enUS完全一致类型系统会强制你补齐所有 key然后注册到 locales.ts#L117-L120 的locales表语言类型扩展 types.ts#L8 的SupportedLanguage联合类型提示词层在 PageAgentCore.ts#L480 的语言映射中补充新语言的名称扩展层在packages/extension/public/_locales/下按 Chrome 语言代码新增目录与messages.json由于 key 路径和结构都由 TypeScript 类型锁定新增语言的成本基本等于「翻译一份文件」。总结page-agent 的 i18n 架构可以概括为「分层治理 类型兜底」UI 文案轻量 I18n 类 编译期类型检查翻译缺失无法逃逸扩展元数据复用 Chrome_locales官方机制零代码成本系统提示词单份英文模板 运行时正则替换AI 思考语言随用户切换三层方案彼此独立又共用SupportedLanguage这一个语言契约既保证了多语言体验的一致性又把架构复杂度控制在了最低。想了解项目更多细节可阅读 docs/developer-guide.md 与 docs/README-zh.md。【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考