GPUI Kit 组件国际化指南:用 rust-i18n 为 gpui-component 新增语言与覆盖翻译
GPUI Kit 组件国际化指南用 rust-i18n 为 gpui-component 新增语言与覆盖翻译【免费下载链接】gpui-kitRust GUI components for building fantastic cross-platform desktop application by using GPUI.项目地址: https://gitcode.com/GitHub_Trending/gp/gpui-kitGPUI Kit 的组件库gpui-component已为日历、日期选择器、下拉框、Dock、对话框等数十类组件内置了多语言文案。本文基于 website/zh-CN/docs/i18n.md 官方文档结合仓库源码与 story 示例应用完整讲解如何在应用中新增语言如fr、覆盖个别翻译、注册 locale 扩展与运行时切换语言。读完本文你将掌握一套不复制内置 locale 文件即可深度定制组件文案的国际化方案。一、概述GPUI Component 的内置翻译能力GPUI Componentcrate 名gpui-component为组件提供了内置翻译目前内置的语言包括en英文也是 fallback 默认语言zh-CN简体中文zh-HK繁体中文香港在此基础上内置 locale 文件还额外携带了zh-TW繁体中文台湾与it意大利语的部分翻译。应用既可以新增一个全新的语言例如文档示例中的法语fr也可以覆盖个别翻译例如把某个组件的某条英文文案改成自定义文本而且完全不需要复制组件库完整的 locale 文件——这正是该方案的核心价值。该功能依赖rust-i18ncrate要求 4.2 或更高版本。在仓库中gpui-component本身正是通过 crates/component/Cargo.toml 中的rust-i18n.workspace true引入该依赖的。组件内部的实际调用点遍布源码各处例如crates/component/src/time/calendar.rs 通过use rust_i18n::t;引入宏并使用t!(Calendar.month.January)等调用读取月份、星期文案crates/component/src/select.rs 使用t!(Select.placeholder)读取下拉框占位文本此外 crates/component/src/dock/panel.rs、crates/component/src/combobox.rs、crates/component/src/dialog/dialog.rs、crates/component/src/input/number_input.rs 等 17 个组件模块均使用rust_i18n::t。二、内置 locale 文件与可用翻译 key组件库内置的翻译存放在 crates/component/locales/ui.yml文件以_version: 2开头与 rust-i18n 4.2 的格式要求一致所有 key 按组件名组织。下面是从内置文件整理的翻译 key 速查表应用在编写自己的 locale 文件时可直接参考这些 key组件namespace翻译 key用途Calendarweek.0~week.6周日到周六的星期缩写Calendarmonth.January~month.December12 个月份名称DatePickerplaceholder日期选择占位文本Selectplaceholder下拉选择占位文本ComboBoxplaceholder/search_placeholder/empty组合框占位、搜索占位、空数据文案DockUnnamed/Close/Zoom In/Zoom Out/Collapse/ExpandDock 面板标题与菜单项ColorPickerPalette/HSLA/Hue/Saturation/Lightness/Alpha取色器面板文案Dialogok/cancel确认 / 取消按钮Commandplaceholder/empty命令面板占位与空结果Listsearch_placeholder列表搜索占位InputDecrement/Increment/Replace/Replace All/Cut/Copy/Paste/Select All/Go to Definition/Show Code Actions输入框右键菜单与数字步进器文案Settingssearch_placeholder/Reset All设置面板文案Paginationprevious/next上一页 / 下一页Carousellabel/previous/next/slide/pagination/go_to_slide轮播无障碍标签含%{current}/%{total}插值其中Carousel的slide与go_to_slide使用了 rust-i18n 的插值语法例如第 %{current} 张共 %{total} 张应用在覆盖这些 key 时同样可以使用插值。三、工作原理namespace 与 deep mergeGPUI Component 国际化机制的关键在于namespace命名空间与deep merge深度合并组件库在编译期通过rust_i18n::i18n!(locales, fallback en)加载自己的内置 locale见 crates/component/src/lib.rs其中fallback en表示查找不到当前语言的 key 时回退到英文。应用提供的 locale 文件必须把组件翻译放在gpui_componentnamespace下。这个 namespace 对应 Rust crate 名称gpui-component其中连字符被转换为下划线。应用启动时通过rust_i18n::extend!(gpui_component)把应用 locale 叠加到组件库的内置 locale 之上两者按 key 做深度合并deep merge应用层优先。四、接入步骤下面按官方文档给出的完整步骤从添加依赖到注册扩展逐一实现。4.1 添加依赖在持有 locale 文件的应用 crate的Cargo.toml中添加rust-i18ngpui-component本身通常已通过gpui-kit的componentfeature 引入[dependencies] gpui-component 0.6 rust-i18n 4.2注意rust-i18n需要 4.2 或更高版本过低版本不支持本文使用的extend!与 namespace 合并机制。4.2 创建应用 locale 文件在应用 crate 中创建locales/ui.yml这是i18n!宏默认约定的目录与文件名将组件翻译放在gpui_componentnamespace 下。以新增法语为例_version: 2 gpui_component: Calendar: week.0: fr: Di month.January: fr: Janvier DatePicker: placeholder: fr: Sélectionner une date要点顶层_version: 2必须保留与 rust-i18n 4.x 的 YAML 格式匹配每个 key 下的语言代码如fr对应一个翻译值namespace 必须是gpui_component下划线形式可查看 crates/component/locales/ui.yml 确认可用的翻译 key 及语言代码。4.3 在应用 crate root 初始化 locales在应用的 crate root通常是main.rs或lib.rs顶部调用rust_i18n::i18n!宏加载应用自己的 locale 文件rust_i18n::i18n!(locales, fallback en);4.4 初始化 GPUI Component 之前注册扩展在应用入口app.run的闭包中在初始化 GPUI Component 之前调用extend!注册扩展app.run(move |cx| { rust_i18n::extend!(gpui_component); gpui_kit::init(cx); // 打开窗口并初始化应用的其他部分。 });extend!接收的是crate 标识符宏会把 crate 名字符串化为 namespace keygpui_component。应用启动期间只需调用一次extend!。该调用必须发生在组件渲染任何文案之前因此放在gpui_kit::init(cx)其内部调用 crates/component/src/lib.rs 的component::init之前。五、查找优先级与合并规则应用提供的翻译优先于组件的内置翻译查找顺序如下应用 localeslocales/ui.yml │ │ 未找到 key ▼ GPUI Component 内置 locales这种 deep merge 行为意味着新语言只需提供需要的 key例如新增fr语言时只为 Calendar、DatePicker 等关心的 key 提供法语翻译即可其余组件仍显示内置英文同 key 覆盖locale 和 key 都相同时应用提供的翻译会覆盖内置值。例如只定义gpui_component.Calendar.month.January.en就会把一月份的英文标签改成自定义文本而其他英文日历标签仍来自 GPUI Component未提供 key 自动回退应用未提供的 key 会继续使用组件内置值天然向前兼容GPUI Component 后续新增的翻译无需复制也会自动可用——你不需要跟随组件库升级而同步维护 locale 文件。六、命名空间的作用域只对组件内部的查找生效需要特别澄清一个容易误解的点extend!改变的是GPUI Component 查找自身 key 的方式它不会让应用自己的t!调用访问到内置翻译// GPUI Component 组件内部先查应用再查内置。 t!(Calendar.month.February) // - February // 应用代码中只会读取应用自己的 locale 文件。 t!(gpui_component.Calendar.month.February) // - 未定义时返回 key 本身原因在于extend!是向gpui_component这个 namespace 追加翻译层组件内部调用t!(Calendar.month.February)时例如 crates/component/src/time/calendar.rs 的month_name函数rust-i18n 会先在应用叠加层查找该 key未命中再查组件内置层而应用代码直接调用t!时读取的只是应用自己的 locale 文件未定义时t!会返回 key 字符串本身。因此组件文案应当通过渲染组件来呈现不要在应用代码里自行查询这些 key。七、运行时切换语言gpui-component已经再导出了 locale 相关方法应用无需直接依赖rust-i18n即可切换语言。这两个方法定义在 crates/component/src/lib.rs#[inline] pub fn locale() - impl DerefTarget str { rust_i18n::locale() } #[inline] pub fn set_locale(locale: str) { rust_i18n::set_locale(locale) }通过gpui-kit门面使用gpui_kit::component即gpui-component的重导出见 crates/kit/src/lib.rsgpui_kit::component::set_locale(fr); let current gpui_kit::component::locale();组件随后会按照前述优先级使用当前 locale 查找翻译文本。重要当前 locale 属于 GPUI 不感知的全局状态修改它本身不会触发重绘。因此展示翻译文本的 view 需要自行通知界面刷新gpui_kit::component::set_locale(fr); cx.notify();如果切换语言发生在 view 的 update 闭包之外应通过cx.update(...)定位到目标 view 后调用view.update(cx, |_, cx| cx.notify())。八、仓库中的真实示例story 应用仓库自带的示例应用crates/story就是这套国际化机制在真实项目中的完整落地可作为接入模板应用 locale 文件crates/story/locales/ui.yml 只包含gpui_componentnamespace 下的法语fr翻译覆盖了 Calendar 的星期与月份、DatePicker 的占位文本其余语言与 key 全部回退到组件内置值初始化宏crates/story/src/lib.rs 在 crate root 调用rust_i18n::i18n!(locales, fallback en)注册扩展crates/story/src/lib.rs 定义了extend_component_translations函数通过use gpui_kit::component as gpui_component;别名后调用rust_i18n::extend!(gpui_component)并在init中于组件初始化前执行运行时切换crates/story/src/app_menus.rs 在SelectLocaleaction 处理器中调用rust_i18n::set_locale(s.0.as_str())随后调用update_app_menu重建菜单crates/story/src/app_menus.rs 通过rust_i18n::locale().to_string()读取当前语言用于菜单勾选状态。注意该示例直接调用rust_i18n::set_locale与文档推荐的gpui_kit::component::set_locale等效——后者正是前者的再导出封装。九、常见问题与注意事项namespace 拼写应用 locale 文件中的 namespace 必须是gpui_component写成gpui-component连字符或其他名称都会导致 extend 后查找不到叠加层文件路径约定rust_i18n::i18n!(locales, ...)默认从 crate 根目录加载locales/目录文件名须为ui.ymlfallback 语言fallback en保证任何未翻译的 key 至少能显示英文建议保持默认只注册一次extend!在应用启动期间只需调用一次重复注册会导致叠加层重复叠加重绘问题切换 locale 后务必对正在显示翻译文案的 view 调用cx.notify()否则界面不会更新版本要求rust-i18n 必须 ≥ 4.2_version: 2的 YAML 格式与该版本配套旧版本可能无法正确解析。按照以上步骤你可以在不复制任何内置 locale 文件的前提下为 GPUI Kit 应用自由扩展语言或定制组件文案并且随组件库升级自动获得新增翻译。【免费下载链接】gpui-kitRust GUI components for building fantastic cross-platform desktop application by using GPUI.项目地址: https://gitcode.com/GitHub_Trending/gp/gpui-kit创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考

相关新闻

国内哪里可以做NAATI翻译?如何办?实操要点一次说清楚

国内哪里可以做NAATI翻译?如何办?实操要点一次说清楚

一、国内哪里可以做NAATI翻译?第一个就是大家用得很多的慧办好翻译小程序,微信、支付宝一搜就能找到。不用受地域限制,只要手机能上网就能办。而且对接的全部是NAATI三级中译英的持证译员,不是随便找个普通翻译就上手,…

2026/11/18 7:33:16 阅读更多 →
Cleanlab 兼容的 PyTorch MNIST CNN 分类器:mnist_pytorch 模块实战指南

Cleanlab 兼容的 PyTorch MNIST CNN 分类器:mnist_pytorch 模块实战指南

Cleanlab 兼容的 PyTorch MNIST CNN 分类器:mnist_pytorch 模块实战指南 【免费下载链接】cleanlab Cleanlabs open-source library is the standard data-centric AI package for data quality and machine learning with messy, real-world data and labels. 项…

2026/11/18 7:33:17 阅读更多 →
法国宣誓翻译驾照怎么办?国内哪里能做?详细流程全说清,新手办理不踩坑

法国宣誓翻译驾照怎么办?国内哪里能做?详细流程全说清,新手办理不踩坑

不少准备去法国自驾的朋友,拿着国内驾照却卡在翻译环节,普通翻译件到当地不被认可,白忙活一场。专门跑线下机构办理还要抽时间请假,来回奔波耗精力,很多人都觉得头疼。可以直接在微信、支付宝进入慧办好翻译小程序提交…

2026/11/18 10:21:47 阅读更多 →

最新新闻

Electron桌面应用开发实战:从环境搭建到打包发布全流程

Electron桌面应用开发实战:从环境搭建到打包发布全流程

做前端这些年,我大部分时间都在跟浏览器标签页打交道,直到第一次把桌面应用跑起来,才发现原来自己一直被限制在地址栏和刷新按钮围起来的框框里。Electron这个词,最开始是在某段时间频繁出现在同事的讨论里,一个用HTML…

2026/11/18 13:59:04 阅读更多 →
滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

简介:亚太天能T109滑盖智能锁产品说明书是一份PDF格式的官方技术文档,主要面向智能锁安装人员、终端用户及售后维护者,帮助快速掌握产品安装、配置与常见故障处理。全包仅1个PDF文件,大小4.37MB,内容结构清晰&#xff…

2026/11/18 15:33:23 阅读更多 →
PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

上个月我在调试一台高速AGV的驱动系统,整车要求空载跑到8m/s,电机转速已经拉到额定点,驱动器的输出电压也顶到了母线电压极限附近。再往上踩速度指令,转速纹丝不动,三相电流反而开始震荡。那会儿我的第一反应就是&…

2026/11/18 17:05:28 阅读更多 →
C++核心知识点:从内存管理到STL的实战指南

C++核心知识点:从内存管理到STL的实战指南

C 这门语言我前前后后折腾了十几年,用它写过嵌入式驱动、做过游戏服务端,也搭过基础组件库。每次看到新人一头扎进"C 核心知识点"这个搜索词,我其实挺感慨的——这门语言的难点从来不是语法多,而是知识点之间的耦合太深…

2026/11/18 14:33:19 阅读更多 →
T109滑盖智能锁怎么装?安装调试与故障排查全攻略

T109滑盖智能锁怎么装?安装调试与故障排查全攻略

简介:亚太天能T109滑盖智能锁产品说明书以PDF格式发布,适合智能锁用户、安装人员与售后维修人员阅读。内容围绕T109系列指纹密码刷卡锁展开,先介绍前面板、后面板、锁体、机械钥匙、电池盒盖等部件名称与功能,再给出完整安装步骤&…

2026/11/18 17:05:28 阅读更多 →
LLM知识降熵:从信息垄断到理解权下放

LLM知识降熵:从信息垄断到理解权下放

你有没有过这种经历:翻开源码注释、论文摘要或者一份专业报告,每个字都认识,连在一起却像天书。想找人聊聊,身边要么没人懂,要么懂的懒得跟你解释。后来我试着把同一段内容丢给一个大语言模型,几秒钟之后&a…

2026/11/18 14:13:08 阅读更多 →

日新闻

周新闻

月新闻