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-agent

page-agent是一个用 JavaScript 实现的页内 GUI Agent，能用自然语言直接控制网页界面。它的国际化（i18n）方案覆盖三层：UI 文案、扩展元数据和系统提示词——本文带你完整看懂这套多语言架构是如何运作的。

项目速览：一个「会操作网页的 AI」

page-agent 的核心思路是让 AI 像人一样点击按钮、填写表单、滚动页面。为了让中文用户获得母语级的体验，项目在三个不同层面分别做了本地化处理，三者互不耦合、各司其职：

层面	作用对象	实现位置
UI 文案层	控制面板的状态、工具动作、错误提示	`packages/ui/src/i18n/`
扩展元数据层	Chrome 商店展示的名称、描述	`packages/extension/public/_locales/`
系统提示词层	发送给大模型的 system prompt	`packages/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-L16）

2. 让 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 个 key（extName、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 user's 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 类型锁定，新增语言的成本基本等于「翻译一份文件」。