前言 最近我在开发一个基于 Plasmo 的 Chrome MV3 浏览器扩展，项目主要用于统一管理 ChatGPT、Claude 等 AI 平台的对话记录，支持账号同步、搜索、收藏、标签、批量操作等功能。 随着功能逐渐完善，扩展里出现了大量 UI 文案、提示信息、错误信息。如果这些文本全部硬编码在组件里，后续维护会非常麻烦： 想支持英文、中文等多语言时，需要到处改代码； popup、content script、background 里都有文案，容易遗漏； Chrome 扩展本身也有名称、描述等 manifest 文案，也需要国际化； 文案带变量时，比如“已选中 5 项”，如果手动拼接，会不利于多语言适配。 因此，我最终使用 Chrome 扩展原生提供的 chrome.i18n API，再结合 Plasmo 的目录约定，给项目做了一套轻量、简单、够用的国际化方案。 本文就结合我的项目实践，介绍如何在 Plasmo 浏览器扩展中实现 i18n。 一、项目技术栈 我的项目是一个 Chrome MV3 扩展，主要技术栈如下： Plasmo React TypeScript Tailwind CSS Chrome Extension Manifest V3 项目结构比较简单，所有源文件都放在项目根目录，没有额外的 src 目录。 核心文件大致如下： my-first-extension/ ├── popup.tsx ├── content.ts ├── background.ts ├── logic.ts ├── db.ts ├── utils/ │ └── i18n.ts ├── locales/ │ ├── en/ │ │ └── messages.json │ └── zh_CN/ │ └── messages.json ├── package.json └── ... 其中和国际化相关的主要是： utils/i18n.ts locales/en/messages.json locales/zh_CN/messages.json package.json 二、Plasmo 项目中的语言包目录 在 Chrome 扩展规范中，最终构建产物里通常会有 _locales 目录，例如： _locales/ ├── en/ │ └── messages.json └── zh_CN/ └── messages.json 而在 Plasmo 项目开发阶段，我们可以直接在项目中创建： locales/ ├── en/ │ └── messages.json └── zh_CN/ └── messages.json Plasmo 构建时会处理这些语言资源，让它们符合 Chrome Extension 的国际化规范。 我的项目里目前支持两种语言： locales/en/messages.json locales/zh_CN/messages.json 其中： en 是英文； zh_CN 是简体中文。 三、在 manifest 中配置默认语言 Chrome 扩展要启用国际化，必须在 manifest 中声明 default_locale 。 在 Plasmo 项目里，可以直接在 package.json 的 manifest 字段里配置： { "manifest": { "default_locale": "en", "permissions": [ "storage", "alarms" ], "host_permissions": [ "https://chatgpt.com/*", "https://claude.ai/*" ] } } 这里我把默认语言设置为英文： "default_locale": "en" 这意味着如果用户当前浏览器语言没有对应的语言包，Chrome 会回退使用英文语言包。 四、扩展名称和描述的国际化 浏览器扩展的名称、描述也可以使用 Chrome i18n 的占位符语法。 我的 package.json 中这样写： { "name": "multi-ai-conversation-manager", "displayName": "__MSG_extName__", "description": "__MSG_extDescription__" } 这里的重点是： "displayName": "__MSG_extName__", "description": "__MSG_extDescription__" __MSG_xxx__ 是 Chrome 扩展国际化的特殊语法。 例如： __MSG_extName__ 会去当前语言包的 messages.json 中查找： { "extName": { "message": "ChatGPT & Claude AI Conversation Manager" } } 中文语言包中对应的是： { "extName": { "message": "ChatGPT、Claude AI 对话管理器" } } 这样一来，扩展在 Chrome 扩展管理页、商店信息或者 manifest 中展示时，就能根据用户浏览器语言自动切换名称和描述。 五、messages.json 的基本格式 Chrome 扩展的语言文件必须叫做 messages.json 。 基本格式如下： { "key": { "message": "具体文案" } } 比如英文语言包： { "account_management": { "message": "Account Management" }, "account_add": { "message": "Add Account" }, "btn_confirm": { "message": "Confirm" }, "btn_cancel": { "message": "Cancel" } } 中文语言包： { "account_management": { "message": "账号管理" }, "account_add": { "message": "添加账号" }, "btn_confirm": { "message": "确认" }, "btn_cancel": { "message": "取消" } } 这里需要注意： 不同语言包里的 key 要保持一致。 也就是说，英文里有： "account_add" 中文里也必须有： "account_add" 否则运行时调用这个 key 时，某些语言环境下就可能取不到翻译。 六、封装一个统一的 t 函数 虽然可以在代码里直接写： chrome.i18n.getMessage("btn_confirm") 但如果项目中大量使用这个 API，会有几个问题： 写起来比较长； 后续如果想增加 fallback 逻辑，需要到处改； popup、content script、background 都会重复使用； 不方便统一处理参数替换。 所以我在项目中封装了一个简单的工具函数。 文件位置： utils/i18n.ts 代码如下： /** * Chrome 扩展国际化工具函数 * 封装 chrome.i18n API，提供类型安全的文本获取方法 */ /** * 获取国际化文本 * @param key - messages.json 中定义的 key * @param substitutions - 可选的替换参数，字符串或字符串数组 * @returns 翻译后的文本，如果 key 不存在则返回 key 本身 */ export function t(key: string, substitutions?: string | string[]): string { return chrome.i18n.getMessage(key, substitutions) || key } 这个函数做了两件事： 第一，简化调用： t("btn_confirm") 比下面这样更简洁： chrome.i18n.getMessage("btn_confirm") 第二，增加 fallback： return chrome.i18n.getMessage(key, substitutions) || key 如果某个 key 没有找到，直接返回 key 本身。这样至少页面不会显示空字符串，调试时也很容易发现哪个 key 没配置。 七、在 React Popup 页面中使用 i18n 我的扩展主要 UI 在 popup.tsx 中，它是一个 React 页面。 首先引入工具函数： import { t } from "./utils/i18n" 然后就可以在 JSX 中使用： <button> {t("account_add")} </button> 或者用于错误提示： return ( <div className="p-4 text-red-500 text-sm"> {t("errorBoundaryMessage")} </div> ) 对应的英文语言包： { "errorBoundaryMessage": { "message": "An error occurred. Please close and reopen the extension" } } 对应的中文语言包： { "errorBoundaryMessage": { "message": "出现错误，请关闭后重新打开扩展" } } 这样，当用户浏览器语言是中文时，会显示中文；如果是英文环境，则显示英文。 八、在 Content Script 中使用 i18n 浏览器扩展不仅 popup 页面需要国际化，content script 也经常需要显示文案。 我的项目中， content.ts 会注入到 ChatGPT 或 Claude 页面中，用于检测当前登录账号。如果发现新账号，会在页面右下角显示一个提示卡片，引导用户同步账号。 同样先引入： import { t } from "./utils/i18n" 然后在创建 DOM 时使用： card.innerHTML = ` <button class="close-btn" aria-label="${t('content_closeAriaLabel')}">×</button> <div class="header"> <div class="text-content"> <h3>${t('content_newAccountTitle')}</h3> <p>${t('content_newAccountDesc', platformName)}</p> </div> </div> <div class="actions"> <button class="btn-ignore">${t('content_btnIgnore')}</button> <button class="btn-add">${t('content_btnSync')}</button> </div> ` 这里有一个带变量的文案： t("content_newAccountDesc", platformName) 比如英文里可能是： { "content_newAccountDesc": { "message": "A new $PLATFORM$ account was detected. Do you want to sync it now?", "placeholders": { "platform": { "content": "$1", "example": "ChatGPT" } } } } 中文里可以是： { "content_newAccountDesc": { "message": "检测到新的 $PLATFORM$ 账号，是否立即同步？", "placeholders": { "platform": { "content": "$1", "example": "ChatGPT" } } } } 这样在代码里只需要传入平台名称： t("content_newAccountDesc", "ChatGPT") 最终 Chrome 会自动把 $1 对应的内容替换进去。 九、在 Background 和业务逻辑中使用 i18n 除了 UI，后台逻辑里也会产生提示信息或错误信息。 比如消息处理器、同步逻辑、错误封装中，也可以统一使用： import { t } from "~utils/i18n" 或： import { t } from "./utils/i18n" 然后： throw new Error(t("error_accountMismatch")) 或者： return { success: false, error: t("error_syncFailed") } 这样有一个好处： 前端展示的错误信息和后台返回的错误信息，都可以使用同一套语言包管理。 对于浏览器扩展来说，popup、content script、background 是不同运行环境，如果不统一管理文案，后期维护会很痛苦。 十、带参数文案的写法 国际化里最常见的问题之一，就是文案里带变量。 比如： 已选中 5 项 不能简单写成： "已选中 " + count + " 项" 因为不同语言的语序可能不一样。 正确做法是放到语言包中： 英文： { "batch_selectedCount": { "message": "$COUNT$ items selected", "placeholders": { "count": { "content": "$1", "example": "5" } } } } 中文： { "batch_selectedCount": { "message": "已选中 $COUNT$ 项", "placeholders": { "count": { "content": "$1", "example": "5" } } } } 代码中调用： t("batch_selectedCount", String(selectedCount)) 如果有多个参数，也可以传数组： t("error_accountMismatch", [oldEmail, newEmail]) 语言包中可以使用： { "error_accountMismatch": { "message": "账号不匹配：当前账号是 $CURRENT$，目标账号是 $TARGET$", "placeholders": { "current": { "content": "$1", "example": "[email protected]" }, "target": { "content": "$2", "example": "[email protected]" } } } } 十一、推荐的 key 命名方式 随着项目变大，语言包会越来越长。如果 key 命名不规范，很容易混乱。 我在项目中采用了按业务模块前缀命名的方式，例如： theme_light theme_dark theme_system account_management account_add account_delete account_sync batch_manage batch_addTag batch_removeTag batch_selectedCount tag_management tag_create tag_rename tag_delete conversation_notFound conversation_total conversation_copyLink content_newAccountTitle content_newAccountDesc content_btnIgnore content_btnSync errorBoundaryMessage error_syncFailed 这种命名方式有几个优点： 一眼能看出文案属于哪个模块； 搜索方便； 不容易和其他模块冲突； 语言包比较容易维护。 我个人不太建议全部写成非常短的 key，例如： title desc button message 因为项目一大，这些 key 很快就会失去语义。 十二、Chrome i18n 的语言选择机制 使用 chrome.i18n 后，不需要我们自己判断用户语言。 Chrome 会根据用户浏览器语言自动选择语言包。 比如项目里有： locales/en/messages.json locales/zh_CN/messages.json 如果用户浏览器语言是中文简体，Chrome 会优先使用： zh_CN 如果用户浏览器语言是英文，则使用： en 如果没有找到对应语言，会回退到 manifest 中配置的： "default_locale": "en" 所以在大多数情况下，我们不需要自己写： navigator.language 也不需要自己维护语言切换逻辑。 十三、Plasmo i18n 实现流程总结 整体流程可以总结为五步。 1. 创建语言包目录 locales/ ├── en/ │ └── messages.json └── zh_CN/ └── messages.json 2. 在 package.json 中配置默认语言 { "manifest": { "default_locale": "en" } } 3. 使用 __MSG_xxx__ 国际化扩展名称和描述 { "displayName": "__MSG_extName__", "description": "__MSG_extDescription__" } 4. 封装 i18n 工具函数 export function t(key: string, substitutions?: string | string[]): string { return chrome.i18n.getMessage(key, substitutions) || key } 5. 在 popup、content script、background 中统一调用 t("btn_confirm") t("batch_selectedCount", String(count)) t("content_newAccountDesc", platformName) 十四、这种方案的优点 我目前这个项目采用的是原生 chrome.i18n 方案，而不是引入 i18next 、 react-intl 之类的第三方库。 原因很简单：对于浏览器扩展来说，原生方案已经足够好用。 它的优点包括： 1. 不需要额外依赖 不需要安装额外 npm 包，减少 bundle 体积。 2. 和 Chrome 扩展天然集成 manifest 中的名称、描述都可以直接使用 __MSG_xxx__ 。 3. popup、content script、background 都能用 只要在扩展环境中，都可以调用： chrome.i18n.getMessage() 4. 构建简单 Plasmo 会处理扩展构建，不需要自己手动生成 _locales 。 5. 维护成本低 对于中小型浏览器扩展项目，这种方案非常轻量。 十五、需要注意的坑 1. 必须配置 default_locale 如果使用了语言包，但是 manifest 没有配置： "default_locale": "en" 扩展可能无法正确加载国际化资源。 2. key 必须在所有语言包中保持一致 比如英文有： "btn_confirm" 中文也应该有： "btn_confirm" 否则在某些语言下会取不到翻译。 3. messages.json 格式不能随便写 Chrome i18n 不是普通 JSON 字典，不能写成： { "btn_confirm": "Confirm" } 必须写成： { "btn_confirm": { "message": "Confirm" } } 4. 占位符要用 $1 、 $2 比如： { "conversation_total": { "message": "$COUNT$ conversations", "placeholders": { "count": { "content": "$1", "example": "10" } } } } 代码中： t("conversation_total", "10") 5. 不建议在代码里拼接多语言句子 不推荐： t("selected") + count + t("items") 推荐： t("batch_selectedCount", String(count)) 因为不同语言的语序可能不一样。 6. content script 中使用 innerHTML 时要注意安全 如果语言包内容完全由开发者自己维护，风险较小。但如果文案来自用户输入，就不要直接拼进 innerHTML 。 我的项目中的语言包是静态文件，由开发者维护，所以可以用于构造提示卡片。但如果要插入用户输入，最好使用 textContent 或做好转义。 十六、适合继续优化的方向 目前这个方案已经可以满足我的项目需求，不过后续还可以继续优化。 1. 给 key 增加 TypeScript 类型约束 现在的 t 函数是： export function t(key: string, substitutions?: string | string[]): string 也就是说 key 是普通字符串。 如果写错了： t("btn_confim") TypeScript 不会报错，只有运行时才会发现。 后续可以自动从 messages.json 生成类型，例如： type I18nKey = | "btn_confirm" | "btn_cancel" | "account_add" | "account_delete" 然后改成： export function t(key: I18nKey, substitutions?: string | string[]): string { return chrome.i18n.getMessage(key, substitutions) || key } 这样可以在开发阶段提前发现 key 拼写错误。 2. 编写脚本检查多语言 key 是否一致 可以写一个 Node.js 脚本，对比： locales/en/messages.json locales/zh_CN/messages.json 检查两个文件的 key 是否完全一致。 比如： en 中有但 zh_CN 中没有 zh_CN 中有但 en 中没有 这对项目变大后非常有用。 3. 拆分语言包 当 messages.json 变得非常大时，可以按模块维护源文件，例如： i18n-source/ ├── account.json ├── batch.json ├── tag.json ├── content.json └── error.json 然后通过脚本合并生成最终的： locales/en/messages.json locales/zh_CN/messages.json 不过对于大多数浏览器扩展项目，一个 messages.json 也完全够用。 十七、完整示例 下面给一个简化版完整示例。 package.json { "name": "multi-ai-conversation-manager", "displayName": "__MSG_extName__", "description": "__MSG_extDescription__", "manifest": { "default_locale": "en", "permissions": [ "storage", "alarms" ] } } locales/en/messages.json { "extName": { "message": "ChatGPT & Claude AI Conversation Manager" }, "extDescription": { "message": "Unified management for ChatGPT and Claude conversations" }, "btn_confirm": { "message": "Confirm" }, "btn_cancel": { "message": "Cancel" }, "batch_selectedCount": { "message": "$COUNT$ items selected", "placeholders": { "count": { "content": "$1", "example": "5" } } } } locales/zh_CN/messages.json { "extName": { "message": "ChatGPT、Claude AI 对话管理器" }, "extDescription": { "message": "统一管理 ChatGPT、Claude 平台的 AI 对话" }, "btn_confirm": { "message": "确认" }, "btn_cancel": { "message": "取消" }, "batch_selectedCount": { "message": "已选中 $COUNT$ 项", "placeholders": { "count": { "content": "$1", "example": "5" } } } } utils/i18n.ts export function t(key: string, substitutions?: string | string[]): string { return chrome.i18n.getMessage(key, substitutions) || key } popup.tsx import { t } from "./utils/i18n" export default function Popup() { const selectedCount = 5 return ( <div> <button>{t("btn_confirm")}</button> <button>{t("btn_cancel")}</button> <p>{t("batch_selectedCount", String(selectedCount))}</p> </div> ) } 结语 在 Plasmo 浏览器扩展项目中实现 i18n，并不一定要引入复杂的国际化框架。 对于大多数 Chrome 扩展来说，直接使用浏览器原生的 chrome.i18n API 就已经足够： manifest 文案使用 __MSG_xxx__ ； 页面和脚本中使用 chrome.i18n.getMessage() ； 封装一个简单的 t() 函数； 使用 locales/en/messages.json 、 locales/zh_CN/messages.json 管理语言包； 对变量文案使用 placeholders。 这种方式简单、轻量、和浏览器扩展生态天然兼容，非常适合 Plasmo 架构下的扩展开发。 我目前的项目就是采用这种方案，同时覆盖了 popup 页面、content script、background 消息处理和错误提示。整体使用下来，维护成本低，也方便后续继续增加更多语言支持。 1 个帖子 - 1 位参与者 阅读完整话题
Inkstone（砚）— 一个为长读、慢写、中英排版而生的极简 Hugo 主题 本帖使用社区开源推广，符合推广要求。我申明并遵循社区要求的以下内容： 我的帖子已经打上 开源推广 标签： 是 我的开源项目完整开源，无未开源部分： 是（MIT，仓库公开，无任何闭源模块、付费功能、赞助渠道） 我的开源项目已链接认可 LINUX DO 社区： 是（仓库 README 末尾设有 LINUX DO 友链，见 README “友链” 段 ） 我帖子内的项目介绍，AI 生成、润色内容部分已截图发出： 是 以上选择我承诺是永久有效的，接受社区和佬友监督： 是 以下为项目介绍正文内容，AI 生成、润色内容已使用截图方式发出 各位佬友好。 分享一个自己写、自己天天在用的 Hugo 主题： Inkstone（砚） 。 起因挺无聊的——我想给自己的博客挑个主题，要求不多：中英双语、长文好看、shortcode 别太抠门。结果找了一圈：要么 i18n 是事后补丁、装上之后 zh-cn 一半 UI 还是英文；要么中文阅读时间按英文单词数算，3000 字的中文长文显示"1 min read"；要么 shortcode 只有 figure 和 youtube，写点 callout / tab / 图表都得自己缝。 折腾两个周末没找到顺手的，索性自己写一个，从 v0.1.0 慢慢迭代到 v0.1.7。 仓库和 Demo 在这： GitHub： GitHub - BerBai/inkstone: A minimal bilingual Hugo template for longreads. Opinionated about CJK typography, two-column whono-flavored layout, and 25 built-in shortcodes. · GitHub 在线 Demo： https://inkstone.125520.xyz/ License：MIT 项目截图 仓库 images/ 目录里的官方截图，3:2 比例，按 Hugo Themes Gallery 规范做的。 它能干嘛 下面这张图是 AI 协助我整理的项目介绍要点（按特性、对比同类主题的差异分类罗列）。按社区规范，AI 生成与润色的内容部分以截图形式发出： 简单说几个我自己用着最舒服的点： CJK 排版是设计目标，不是适配项 。阅读时间按字符数算，中英混排的标点、引号、行高都调过； i18n 一开始就在主题里 ，不是后补的。中英两套 UI 字符串都全，要加别的语言复制一份 toml 翻译就行； 25+ 内置 shortcode ：callout / admonition / tab / gallery / video / mermaid / markmap / antv-g2 / 图表对比 / 豆瓣卡片……写长文那些花活儿基本不用再自己写； Tailwind v4 走 Hugo 0.128+ 自带的 css.TailwindCSS ，不用单独跑 PostCSS / Vite 这一套构建链； Pagefind 搜索 内置 ⌘K modal，按需启用； 深色模式 跟系统 + localStorage 持久化。 不适合追求花哨动效、瀑布流卡片、落地页式滚动叙事——不是它的设计目标，这一点想先说清楚，免得佬友 clone 下来才发现不是自己要的菜。 三分钟跑起来 前置：Hugo extended ≥ 0.128。 hugo new site mysite cd mysite git init git submodule add https://github.com/BerBai/inkstone themes/inkstone # 装 Tailwind v4 CLI npm init -y && npm install -D tailwindcss @tailwindcss/cli echo 'theme = "inkstone"' >> hugo.toml hugo server 打开 http://localhost:1313/ ，首页就出来了。 不想装 Node 的话也行，主题支持 Tailwind standalone CLI（ brew install tailwindcss 即可），README 里写了三条路径和各自踩过的坑。 适合谁 想写中英双语博客的人 主要写长文、希望排版克制干净的人 不想折腾 CSS 构建链的人 想要一个能直接覆盖 partial / shortcode 来魔改的底座 写在最后 第一次在 LINUX DO 发开源推广，规则读了几遍，希望没踩坑。 欢迎佬友们 star、提 issue、提 PR，或者直接评论区拍砖。 如果你也在折腾 Hugo / 静态博客 / 中英双语写作，希望 Inkstone 能帮上忙。 1 个帖子 - 1 位参与者 阅读完整话题
本帖使用社区开源推广，符合推广要求。我申明并遵循社区要求的以下内容： 我的帖子已经打上 开源推广 标签： 是 我的开源项目完整开源，无未开源部分： 是 我的开源项目已链接认可 LINUX DO 社区： 是 我帖子内的项目介绍，AI生成、润色内容部分已截图发出： 是 以上选择我承诺是永久有效的，接受社区和佬友监督： 是 以下为项目介绍正文内容 背景 我不是中国人，但需要用 QQ 跟中文朋友交流。QQ 全中文界面对外国人很不友好，每次都要猜按钮在哪、菜单是什么意思。于是写了一个 LiteLoaderQQNT 插件，把整个 QQ 界面翻译成任意语言。 反过来用也行：如果你有不懂中文的朋友要用 QQ，装上这个插件他们也能看懂。 效果对比 翻译前： 翻译后（英文）： 功能 翻译按钮、菜单、设置、下拉、聊天预览、消息内容 输入框右键或按 Ctrl+Shift+T 翻译自己打的字（原文/译文切换） 聊天工具栏一键翻译按钮 三级缓存（内存 / 静态词典 / IndexedDB），重复文本瞬时翻译 鼠标悬停译文可查看原始中文 UI 标签、聊天预览、消息三个开关独立控制 支持任意 DeepLX 兼容接口，不需要 API key 设置界面 使用风险提醒 LiteLoaderQQNT 本身有被封号的风险，腾讯自 2024 年底起在主动检测修改版 QQNT 客户端。虽然本插件只做本地 UI 翻译，不碰消息流、不自动化任何行为（风险最低的那一类），但底层加载器仍可能触发检测。建议小号使用。 GitHub github.com GitHub - 0-don/LiteLoaderQQNT-i18n: QQ i18n: Translate QQ's entire Chinese UI into any... QQ i18n: Translate QQ's entire Chinese UI into any language. LiteLoaderQQNT plugin. 欢迎 star 和反馈！ 1 个帖子 - 1 位参与者 阅读完整话题