agentsview 前端本地化实战基于 Paraglide JS 的消息编写、格式化与语言切换完整指南【免费下载链接】agentsviewLocal-first session search, analytics, insights, and token use statistics for coding agents, supporting Claude Code, Codex, and more than 20 other agents.项目地址: https://gitcode.com/GitHub_Trending/ag/agentsviewagentsview 是一个面向编码 Agent 的本地优先会话搜索与洞察平台其 Svelte 前端使用 Paraglide JSinlang 生态实现国际化i18n。本文基于仓库中.agents/skills/localization-paraglide/的完整技能规范系统讲解 agentsview 前端本地化的工作流、消息message编写规则、复数/序数/日期时间/相对时间/数字货币等高级格式化用法以及语言切换与编译校验的完整闭环。读完本文你将掌握为 agentsview 前端新增或修复本地化文案、编写符合规范的多语言 catalog、并正确使用 Paraglide 生成消息函数的全部实操方法。一、本地化架构概览inlang 项目与 Paraglide 生成层agentsview 前端的 i18n 建立在 inlang 项目之上其核心配置文件为 frontend/project.inlang/settings.json{ $schema: https://inlang.com/schema/project-settings, baseLocale: en, locales: [en, zh-CN, zh-TW, ko, fr, ja], modules: [ ./node_modules/inlang/plugin-message-format/dist/index.js, ./node_modules/inlang/plugin-m-function-matcher/dist/index.js ], plugin.inlang.messageFormat: { pathPattern: ./messages/{locale}.json } }关键点baseLocale为en共支持 6 种语言en、zh-CN、zh-TW、ko、fr、ja消息以 JSON 文件形式按语言存放路径模式为./messages/{locale}.json即 frontend/messages/en.json、frontend/messages/zh-CN.json 等消息目录中的每个键key在编译后会生成强类型的 Paraglide 消息函数组件通过应用包装层调用。项目在 frontend/package.json 中引入inlang/paraglide-js版本^2.20.2并通过i18n:compile脚本将消息编译为 TypeScript 代码i18n:compile: paraglide-js compile --project ./project.inlang --outdir ./src/lib/paraglide --strategy localStorage preferredLanguage baseLocale --emit-ts-declarations --silent该命令从project.inlang项目读取配置与消息输出到./src/lib/paraglide并指定localStorage preferredLanguage baseLocale的语言解析策略——这正是语言切换与持久化能够协同工作的底层机制。二、应用侧 i18n 包装层唯一对外入口agentsview 将 Paraglide 的运行时与消息封装在 frontend/src/lib/i18n/index.ts 中这是组件与 Paraglide 生成的代码之间的唯一标准入口。它导出了以下关键内容export { m } from ../paraglide/messages.js; export { getLocale }; export const DEFAULT_LOCALE en; export const LOCALE_STORAGE_KEY agentsview-locale; export const SUPPORTED_LOCALES [en, zh-CN, zh-TW, ko, fr, ja] as const; export type SupportedLocale (typeof SUPPORTED_LOCALES)[number];m编译生成的 Paraglide 消息函数集合组件通过import { m } from ../../i18n/index.js使用getLocale当前激活的 BCP 47 语言标签如en、zh-CN供 kit-ui 组件等接收localeprop 的日期/提示格式化使用避免跟随浏览器语言而非应用语言设置LOCALE_STORAGE_KEY语言持久化使用的 localStorage 键名agentsview-locale。语言选择逻辑由normalizeLocale与matchingLocale实现对浏览器传入的语言标签做归一化例如en-*一律归为enzh-Hans归为zh-CNzh-Hant/zh-TW-*归为zh-TW无法匹配时回退到DEFAULT_LOCALE。初始化时chooseInitialLocale()依次检查 localStorage 中存储的语言、浏览器navigator.languages列表最后回退到ensetLocale()则同时调用 Paraglide 的setLocale并写入 localStorage。应用入口通过initI18n()完成语言初始化export function initI18n() { setLocale(chooseInitialLocale()); }三、本地化工作流从编辑到编译校验的完整步骤根据 .agents/skills/localization-paraglide/SKILL.md为 agentsview 前端新增或修改本地化文案时遵循以下标准流程动手前先读阅读 frontend/project.inlang/settings.json、frontend/src/lib/i18n/index.ts 以及附近的本地化组件确认既有约定与键的命名风格写入双语 catalog把面向用户显示的文案写入 frontend/messages/en.json 和 [frontend/messages/zh-CN.json]两个文件必须使用完全一致的键key集合引入应用本地化入口在组件中通过frontend/src/lib/i18n/index.ts导入import { m } from ../../i18n/index.js;以函数调用方式使用消息例如m.nav_sessions()或m.shared_active_filters_remove_agent({ agent })复数、数字、日期时间、相对时间当被格式化的值属于可翻译文案的一部分时使用 Paraglide 消息声明declaration而非手工拼接字符串独立可见的日期/时间标签使用 frontend/src/lib/i18n/index.ts 导出的formatDateTime()使其跟随当前激活的 Paraglide locale保持技术标识不翻译Agent 名称、模型名称、文件路径、CLI 命令、ID 和原始 API 值一律不翻译编译与校验在frontend/目录下依次运行npm run i18n:compile和npm run check。最后一步是每次消息或组件改动后的强制性收尾i18n:compile重新生成src/lib/paraglide下的代码check即svelte-check则负责类型检查确保所有消息调用签名正确。四、消息编写规则与命名规范SKILL 文档明确规定了消息message层面的约束键名要限定作用域且具描述性例如settings_terminal_title、activity_concurrency_empty。从 frontend/messages/en.json 中可以看到大量遵循模块_组件_语义风格的键如nav_sessions、header_actions_export_session、message_content_pin_message键名天然携带了功能归属信息便于检索与维护不要拼接已翻译的句子片段优先使用带参数parameter的完整消息。例如在 JSON 中定义header_actions_cycle_layout: Cycle layout: {layout} (l)组件调用m.header_actions_cycle_layout({ layout })而不是把 Cycle layout: 与 layout 标签分开翻译再拼起来复数消息传数字不要传字符串传给复数化消息的必须是数值仅当展示片段已被有意格式化时才传字符串Svelte 中的响应式更新当数组或对象包含翻译后的标签并且需要随语言切换重新渲染时将其放入$derived或$derived.by中保证 locale 变化后派生值重新求值不要绕过包装层组件中不得直接从frontend/src/lib/paraglide/*导入除非正在修改 i18n 包装层本身一律经i18n/index.ts使用。五、格式化参考复数、序数、日期时间、相对时间与货币当需要把数值、日期等动态值嵌入可翻译文案时请在消息声明中直接使用 Paraglide 的格式化器formatter完整规范见仓库内的 .agents/skills/localization-paraglide/references/paraglide-formatting.md。5.1 生成消息的基础用法消息存放在frontend/messages/{locale}.json英文与简体中文 catalog 键必须一一对应。编译后通过应用包装层调用import { m } from ../../i18n/index.js; m.greeting({ name: Ada });5.2 基数复数Cardinal PluralsParaglide 的pluralselector 基于Intl.PluralRules因此对拥有超过英语 singular/other 两种类别的语言同样有效。agentsview 实际消息中大量使用这一模式例如 frontend/messages/en.json 中的tool_call_group_call_count{ tool_call_group_call_count: [ { declarations: [ input count, local countPlural count: plural ], selectors: [countPlural], match: { countPluralone: {count} tool call, countPluralother: {count} tool calls } } ] }调用时传入数字m.tool_call_group_call_count({ count: 3 });对于zh-CN使用相同的声明并提供对应的中文文案只有当该语言确实不存在可见的复数区别时一个other或通配*分支才足够。仓库中的简体中文 catalog 正是如此实践——例如 frontend/messages/zh-CN.json 中parallel_group_call_count只声明了countPluralother: {count} 次调用{ parallel_group_call_count: [ { declarations: [input count, local countPlural count: plural], selectors: [countPlural], match: { countPluralother: {count} 次调用 } } ] }5.3 序数Ordinals对于 1st、2nd、3rd 这类序数使用typeordinal声明。示例ranking_place{ ranking_place: [ { declarations: [ input place, local placePlural place: plural typeordinal ], selectors: [placePlural], match: { placePluralone: {place}st, placePluraltwo: {place}nd, placePluralfew: {place}rd, placePlural*: {place}th } } ] }注意通配分支*用于兜底所有未显式列出的类别。5.4 日期与时间当日期属于可翻译文案的一部分时在消息声明中使用 Paraglide 的datetimeformatter让本地化格式与词序都留在 catalog 中{ session_started_at: [ { declarations: [ input startedAt, local started startedAt: datetime dateStylemedium timeStyleshort ], match: { startedAt*: Started {started} } } ] }而组件中独立可见的日期/时间标签则使用包装层导出的formatDateTime()import { formatDateTime } from ../../i18n/index.js; formatDateTime(timestamp, { month: short, day: numeric, timeZone, });其实现基于Intl.DateTimeFormat并使用当前 Paraglide localeexport function formatDateTime( value: Date | number | string, options: Intl.DateTimeFormatOptions {}, ): string { return new Intl.DateTimeFormat(getLocale(), options).format(new Date(value)); }在仓库中formatDateTime被广泛用于会话列表、活动时间线与摘要卡片等场景例如 frontend/src/lib/components/activity/SessionsTable.svelte、frontend/src/lib/components/analytics/ActivityTimeline.svelte 等组件中均有调用。硬性约束不要在可见 UI 格式化中硬编码en或en-US仅在内部哨兵计算格式化结果不展示给用户时允许使用固定 locale。5.5 相对时间Relative Dates使用 Paraglide 的relativetimeformatterunit选项必填{ status_bar_synced_ago: [ { declarations: [ input duration, local formattedDuration duration: relativetime unitminute numericauto ], match: { duration*: synced {formattedDuration} } } ] }当单位由调用方有意识地动态计算时才使用变量单位通过unit$unit引用输入{ updated_relative: [ { declarations: [ input duration, input unit, local formattedDuration duration: relativetime unit$unit styleshort ], match: { duration*,unit*: Updated {formattedDuration} } } ] }5.6 数字与货币嵌入消息中的数字优先使用 Paraglide 的numberformatter{ usage_total_cost: [ { declarations: [ input amount, local cost amount: number stylecurrency currencyUSD ], match: { amount*: Total cost {cost} } } ] }仅在非句子式标签中且浏览器/应用级 locale 行为已是有意设计时才直接使用toLocaleString()。六、多语言 catalog 的实际形态与键一致性frontend/messages/en.json 与 frontend/messages/zh-CN.json 是目前仓库中规模最大的两个 catalog分别约 2100 余行键完全镜像对齐。英文 catalog 中大量消息携带参数占位符例如nav_search_sessions_shortcut: Search sessions ({shortcut})中文 catalog 则给出对应翻译如nav_search_sessions_shortcut: 搜索会话 ({shortcut})。同时中文 catalog 中也存在 48 处declarations复数/格式化声明与英文 catalog 的声明模式一一对应但匹配分支按语言实际需要裁剪——这是“相同键、语言化分支”这一规范的具体落地。值得注意的是翻译内容中也遵循了“技术标识不翻译”的规则例如tool_call_group_copy_tool_calls: 复制 tool calls、subagent_inline_label: Subagent 会话等保留了产品术语与专有名词原文。七、语言切换与 locale 驱动的组件行为语言切换通过包装层的setLocale()完成它会同步 Paraglide 运行时并持久化到 localStorageexport function setLocale(value: SupportedLocale) { setParaglideLocale(value); try { localStorage?.setItem(LOCALE_STORAGE_KEY, value); } catch { // Ignore storage failures; the active in-memory locale still changes. } }当 locale 变化时所有经m.*渲染的消息以及formatDateTime()格式化的日期都会立即跟随切换。测试代码验证了这一点例如 frontend/src/lib/components/content/MessageList.test.ts 中先setLocale(en)再setLocale(zh-CN)分别断言不同语言下的渲染结果frontend/src/lib/components/content/CodeBlock.svelte.test.ts 也采用同样的双语言断言模式确保消息切换真正生效。此外getLocale还被导出用于把当前语言传给 kit-ui 组件如日期、提示框的格式化使组件内部格式化跟随应用语言设置而非浏览器语言这在i18n/index.ts的注释中已有明确说明。八、实战自查清单在完成一次本地化改动后可按以下清单自检两个 catalog至少en.json与zh-CN.json的键集合完全一致没有漏加或误删所有面向用户显示的文案都已放入 catalog组件中没有硬编码的英文可见文本技术标识Agent/模型名、路径、CLI 命令、ID、API 值保持原文不翻译复数/日期/数字/相对时间均通过 Paraglide 声明实现未手工拼接翻译片段独立日期标签使用formatDateTime()未硬编码en-USSvelte 中含翻译标签的数组/对象放入$derived/$derived.by在frontend/下执行npm run i18n:compile与npm run check两者均通过组件导入一律来自i18n/index.js未直接从src/lib/paraglide/*导入。【免费下载链接】agentsviewLocal-first session search, analytics, insights, and token use statistics for coding agents, supporting Claude Code, Codex, and more than 20 other agents.项目地址: https://gitcode.com/GitHub_Trending/ag/agentsview创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考