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），仅供参考