Carbon React 全球化G11n实践translateWithId、locale 感知与 RTL 布局全解析【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon本文基于 Carbon 官方维护的全球化笔记 g11n.md系统讲解carbon/react组件库的多语言支持机制如何通过 props 注入可翻译文案、translateWithId与 i18n 工具如 react-i18next的 API 兼容性约定、列表组件的 locale 敏感排序、DatePicker的locale/dateFormat配置以及carbon/styles借助 CSS 逻辑属性原生支持 RTL 的原理。读完本文你能够独立为 Carbon React 应用接入完整的多语言与从右到左RTL布局能力。一、核心文档定位Carbon 官方全球化注意事项Carbon React 对国际化的官方指引集中在 packages/react/docs/g11n.md。该文档给出了 6 条核心原则本文逐条展开并结合源码佐证简单组件可翻译字符串直接通过 React props 提供部分组件提供translateWithIdprop其 API 与react-i18next库兼容列表型组件如AccordionItem需按 locale 特定的排序规则排列支持自定义排序的组件如DataTable应让自定义排序逻辑考虑 locale 规则日期相关组件DatePicker依赖 Flatpickr 的 G11N 能力需正确设置locale与dateFormat布局样式使用 CSS 逻辑属性与逻辑值RTL 样式开箱即用不再需要 RTLCSS 之类的后处理工具。二、props 注入简单组件的文案国际化对于文案较简单的组件Carbon 的设计哲学是不内置翻译逻辑而是把字符串暴露为可覆写的 props。开发者可以用任意语言直接传入目标文案无需引入 i18n 框架。例如按钮、表单标签这类组件文案通常就是label、title、children等常规 props翻译工作完全交给业务层的字典。官方建议在组件文档站对应页面查看每个组件可覆写的文案 props原文档指向 react.carbondesignsystem.com 的 Show Info 面板本文不再外链。从仓库源码看这一约定贯穿所有基础组件组件默认导出英文兜底文案同时允许 props 覆盖。三、translateWithId与 react-i18next 兼容的翻译钩子对于文案较多、需要插值如 Page 1 of 10的复杂组件Carbon 提供了translateWithIdprop 作为统一的翻译入口。其类型定义位于 types/common.tsexport interface TranslateWithIdMID string, ARGS Recordstring, unknown { /** * Translates component strings using your i18n tool. * param messageId - The translation ID for the string to translate. * param [args] - Arguments for string interpolation. * returns The translated string. */ translateWithId?(messageId: MID, args?: ARGS): string; } export type TFuncK, A Recordstring, unknown NonNullable TranslateWithIdK, A[translateWithId] ;两个关键设计点API 与 react-i18next 的t函数兼容translateWithId(messageId, args?)的签名消息 ID 插值参数与 react-i18next 的t函数一致因此可以直接把自己的 i18n 函数原样传入import { useTranslation } from react-i18next; function MyPage() { const { t } useTranslation(); return ( PaginationNav totalItems{100} itemsDisplayedOnPage{10} translateWithId{t} / ); }不传也有兜底每个提供该 prop 的组件都内置了一份默认英文翻译与defaultTranslateWithId函数未接入 i18n 时组件仍正常工作。从源码看翻译 ID 的组织方式以PaginationNav为例PaginationNav.tsx翻译 ID 采用命名空间化的常量表 默认翻译字典 默认函数三件套模式const translationIds { carbon.pagination-nav.next: carbon.pagination-nav.next, carbon.pagination-nav.previous: carbon.pagination-nav.previous, carbon.pagination-nav.item: carbon.pagination-nav.item, carbon.pagination-nav.active: carbon.pagination-nav.active, carbon.pagination-nav.of: carbon.pagination-nav.of, } as const; type TranslationKey keyof typeof translationIds; const defaultTranslations: RecordTranslationKey, string { [translationIds[carbon.pagination-nav.next]]: Next, [translationIds[carbon.pagination-nav.previous]]: Previous, [translationIds[carbon.pagination-nav.item]]: Page, [translationIds[carbon.pagination-nav.active]]: Active, [translationIds[carbon.pagination-nav.of]]: of, }; const defaultTranslateWithId: TFuncTranslationKey (messageId) { return defaultTranslations[messageId]; };这种组织方式带来三个好处翻译 ID 是编译期常量as constkeyof typeof推导TranslationKey组件内部调用t(translationIds[carbon.pagination-nav.next])时可获得完整的类型检查翻译键写错会在 TS 编译期报错翻译资源命名空间清晰所有 ID 均以carbon.开头并按组件细分如carbon.pagination-nav.*方便在 i18next 资源文件中按组件归类默认函数可整体替换组件 props 解构时采用translateWithId: t defaultTranslateWithId的形式未传参时自动落到默认英文字典。目前仓库中提供translateWithId的组件覆盖了大量含内置文案的复杂组件例如PaginationNav、Dropdown、ComboBox、MultiSelect、FilterableMultiSelect、ListBox系列、Slider、NumberInput、ProgressIndicator、ComboButton、InterstitialScreen、DataTable含TableHeader、TableBatchActions、TableToolbarSearch以及 Fluid 系列的FluidComboBox、FluidDropdown、FluidMultiSelect、FluidNumberInput等。需要枚举全部可用翻译键时可在仓库中检索translationIds新式写法或translationKeys旧式写法——这正是官方 g11n 文档给出的发现全部字符串 ID 的方法。四、列表型组件的 locale 敏感排序文档指出像AccordionItem这类承担列表项职责的组件其展示顺序应遵循 locale 特定的排序规则。含义是当列表项文案随语言变化时例如德语、中文环境下条目文本不同如果排序逻辑基于字符串字典序排序结果会随语言漂移甚至违背用户预期中文应按拼音/笔画、日语应支持平假名/片假名/数字的不同排序规则等。工程上的正确做法是稳定键优先列表项应保留与语言无关的稳定标识如id、key展示顺序由业务层按 locale 规则预先计算好再传入而不是在渲染期对翻译后字符串做排序使用 locale 感知比较器如确需按文本排序应使用 ICU 级比较规则如Intl.Collator而非原始String.prototype.localeCompare默认行为确保同一数据集在不同 locale 下排序一致且符合当地习惯。这一原则同样适用于Tree/TreeView、Accordion等任何渲染有序子项的组件。五、DataTable 自定义排序让比较函数 locale 感知DataTable支持自定义排序sort回调官方文档明确指出自定义排序逻辑应当把 locale 特定的排序规则纳入考虑。相关说明位于 DataTable README 的 Custom Sorting 小节。典型反模式与正模式对比// 反模式英文字母序硬编码法语/中文等 locale 下结果不可预期 sort{({ column }) { const key column.key; return (a, b) a[key] b[key] ? 1 : -1; }} // 正模式使用 Intl.Collator 按当前 locale 排序 const collator new Intl.Collator(currentLocale); // 如 fr-FR sort{({ column }) { const key column.key; return (a, b) collator.compare(String(a[key]), String(b[key])); }}配合translateWithIdDataTable的表头批量操作按钮、工具栏搜索占位符等内置文案见 TableBatchActions.tsx、TableToolbarSearch.tsx也可同步接入 i18n实现表格文案 排序行为双重国际化。六、DatePickerlocaledateFormat双 prop 配置Carbon 的日期选择组件依赖 Flatpickr 库的 G11N 能力。g11n 文档给出的操作要点是同时设置locale与dateFormat两个 props 才能完整启用 Flatpickr 的国际化此外凡是组件中展示日期/时间的地方都要按目标 locale 的格式习惯正确格式化。两个 prop 的分工详见 DatePicker.mdxlocale传给底层 Flatpickr 实例决定控件内部文案月份名、星期缩写等使用哪种语言。合法取值即 Flatpickr 内置语言包列表dateFormat决定输入框内日期值的展示格式遵循 Flatpickr 的格式化 token如Y四位年、m零填充月、d零填充日。文档给出的标准用法示例// Load Norwegian text with the proper date format DatePicker localeno dateFormatd/m/Y datePickerTypesingle DatePickerInput placeholderdd/mm/yyyy / /DatePicker以及纯格式示例DatePicker datePickerTypesingle dateFormatY-m-d DatePickerInput placeholdermm/dd/yyyy / /DatePicker仓库测试进一步印证了localeprop 的行为边界DatePicker-test.jslocale既接受字符串如localees也接受带locale键的对象locale{{ locale: es }}即直接透传 Flatpickr 的语言包对象未传locale时回退默认语言月/日先后顺序由 locale 规则驱动测试断言localeen时按月-年顺序渲染localeja时按年-月顺序渲染——这正是locale 影响布局顺序的典型场景对年-月型 locale如lv拉脱维亚语组件在月份/年份导航时会正确更新显示标签。另外mdx 文档还补充了一个易被忽略的细节配置dateFormat时可同时提供parseDate函数用于修正原生 Date 方法在解析非标准格式字符串时的边界行为详见 mdx 的 DatePickerparseDate 小节。如果你在其他 Carbon 组件中自行展示日期非DatePicker请务必自行按 locale 格式化组件不会替你处理。七、RTL 开箱即用CSS 逻辑属性取代 RTLCSSg11n 文档的最后一项结论是 Carbon 样式体系的重大变化carbon/styles以及构建其上的carbon/react在布局上全面使用 CSS 逻辑属性logical properties与逻辑值因此 RTL从右到左样式开箱即用。逻辑属性的含义margin-left→margin-inline-start、inset-right→inset-inline-end、text-align: left→text-align: start等。逻辑属性会随文档dir属性ltr/rtl自动翻转方向无需为 RTL 单独生成一份 CSS历史背景在早期版本中消费方项目必须引入 RTLCSS 之类的工具在构建期将物理方向属性批量重写为 RTL 版本文档明确声明这一要求已取消源码佐证在 packages/styles/scss 目录中inset-inline、margin-inline、padding-inline等逻辑属性被大量使用例如 _accordion.scss18 处、_tearsheet.scss16 处、_button.scss11 处、_breadcrumb.scss9 处等组件样式文件均如此。消费方接入 RTL 的标准做法html dirrtl langar仅需在文档根节点声明dirrtlCarbon 组件的箭头、偏移、内边距等布局即自动镜像无需额外的 CSS 构建步骤或样式覆写。八、小结Carbon React G11n 接入检查清单场景手段关键 props / API简单文案组件直接覆写字符串 propslabel、title等复杂组件内置文案注入 i18n 函数translateWithId签名兼容 react-i18next 的t枚举翻译键源码检索translationIds/translationKeys列表项排序稳定键 locale 感知比较器Intl.Collator避免对翻译后文本硬编码排序DataTable 自定义排序比较函数 locale 感知sort回调见 DataTable README 的 Custom Sorting日期控件Flatpickr G11NlocaledateFormat必要时parseDateRTL 布局CSS 逻辑属性根节点dirrtl无需 RTLCSS以上机制的权威出处是 g11n.md本文中的类型定义、翻译 ID 组织、DatePicker 测试与样式逻辑属性均给出对应仓库内路径可据此继续深入。【免费下载链接】carbonA design system built by IBM项目地址: https://gitcode.com/GitHub_Trending/carbo/carbon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考