Material UI 本地化完全指南createTheme Locale 配置、57 种语言支持、自定义翻译与 RTL【免费下载链接】material-uiMaterial UI: Comprehensive React component library that implements Googles Material Design. Free forever.项目地址: https://gitcode.com/GitHub_Trending/ma/material-ui本篇技术指南基于 Material UIMUI官方文档 Localization 展开系统讲解如何为基于mui/material的 React 应用配置非默认语言从使用createTheme全局注入 locale 文本、理解 locale 对象内部结构与defaultProps生效链路到创建自定义翻译、处理阿拉伯语等 RTL 语言。读完本文你可以独立完成多语言应用搭建、为组件文本做定制覆盖并理解本地化文本在源码层面的具体落地方式。什么是 Material UI 的本地化本地化Localization又称 l10n指将产品或内容适配到特定区域locale或市场的过程。Material UI 的默认语言环境是英语美国en-US。当你的应用面向其他语言用户时只需在主题中声明对应的 locale 对象组件内置的用户可见文本分页、评分、自动完成、面包屑、警告提示等即会切换为对应语言的文案。需要特别说明Data Grid 与 Data Grid Pro属于 MUI X 产品线它们拥有独立的本地化体系不适用本文介绍的mui/material/locale配置方式需要按 MUI X 文档单独配置。通过 createTheme 全局配置 locale 文本官方推荐的方式是把 locale 对象作为createTheme的第二个参数传入从而把本地化文本配置应用到整个主题树中import { createTheme, ThemeProvider } from mui/material/styles; import { zhCN } from mui/material/locale; const theme createTheme( { palette: { primary: { main: #1976d2 }, }, }, zhCN, ); ThemeProvider theme{theme} App / /ThemeProvider;其中zhCN是简体中文 locale从mui/material/locale命名空间导入。导入后ThemeProvider包裹的整棵组件树内所有受本地化影响的组件文本都会使用中文。源码机制第二个参数是如何进入主题的locale 对象并非特殊 API而是走主题的通用深层合并通道。从 createTheme 的签名createTheme(options, ...args)可以看出所有额外的实参都会传给createThemeNoVars在那里执行// packages/mui-material/src/styles/createThemeNoVars.jsL117-L118 muiTheme deepmerge(muiTheme, other); muiTheme args.reduce((acc, argument) deepmerge(acc, argument), muiTheme);也就是说zhCN会被整体deepmerge进主题对象。观察 zhCN.ts 可以发现locale 对象的顶层结构只有一个components键其下按组件名挂defaultProps。例如// packages/mui-material/src/locale/zhCN.ts节选 export const zhCN: Localization { components: { MuiTablePagination: { defaultProps: { getItemAriaLabel: (type) { if (type first) return 第一页; if (type last) return 最后一页; if (type next) return 下一页; return 上一页; }, labelRowsPerPage: 每页行数:, labelDisplayedRows: ({ from, to, count }) 第 ${formatNumber(from)} 条到第 ${formatNumber(to)} 条${count ! -1 ? 共 ${formatNumber(count)} 条 : 至少 ${formatNumber(to)} 条}, }, }, // MuiRating、MuiAutocomplete、MuiAlert、MuiPagination、MuiBreadcrumbs ... }, };这些defaultProps之所以能生效是因为组件渲染时通过useThemeProps/getThemeProps从主题中读取theme.components[组件名].defaultProps并与用户传入的 props 做解析。核心实现在 getThemeProps.tsconst { theme, name, props } params; if (!theme || !theme.components || !theme.components[name] || !theme.components[name].defaultProps) { return props; } return resolveProps(theme.components[name].defaultProps, props);resolveProps遵循显式 props 优先于 defaultProps的解析规则。因此本地化只提供组件的默认文案业务侧任何显式传入的 prop例如给TablePagination传自定义labelDisplayedRows都会覆盖 locale 提供的文本——这为整体换语言 个别组件定制的组合使用留出了空间。locale 对象的结构Localization 接口所有 locale 文件都实现同一个类型契约定义在 LocaleTextApi.tsexport interface Localization { components?: { MuiAlert?: { defaultProps: PickComponentsPropsList[MuiAlert], closeText }; MuiBreadcrumbs?: { defaultProps: PickComponentsPropsList[MuiBreadcrumbs], expandText }; MuiTablePagination?:{ defaultProps: Pick..., labelRowsPerPage | labelDisplayedRows | getItemAriaLabel }; MuiRating?: { defaultProps: Pick..., emptyLabelText | getLabelText }; MuiAutocomplete?: { defaultProps: Pick..., clearText | closeText | loadingText | noOptionsText | openText }; MuiPagination?: { defaultProps: Pick..., aria-label | getItemAriaLabel }; }; }这份类型说明了本地化影响的组件与可翻译的文本位点Alert的关闭文本、Breadcrumbs的展开文本、TablePagination的每页行数/显示行数标签与按钮 aria-label、Rating的评分标签与空值标签、Autocomplete的清空/关闭/加载/无选项/打开提示文本以及Pagination的导航 aria-label 与单项 aria-label。值得注意的是源码注释核心包不依赖mui/lab因此MuiPagination的 props 是内联复制定义的而非引用ComponentsPropsList这解释了为什么Pagination的defaultProps只含aria-label与getItemAriaLabel两项。locale 中的数字格式化还依赖 buildFormatNumber它以Intl.NumberFormat按目标区域如zh-CN生成格式化器对非有限值或运行环境不支持Intl时优雅降级为String(value)保证 SSR 与老旧环境的健壮性。动态切换语言的官方示例文档中的交互示例 Locales.js 演示了运行时按用户选择切换语言用Autocomplete列出Object.keys(locales)作为可选项选中后用createTheme(theme, locales[locale])重建主题并包一层新的ThemeProviderimport * as locales from mui/material/locale; const themeWithLocale React.useMemo( () createTheme(theme, locales[locale]), [locale, theme], ); return ( ThemeProvider theme{themeWithLocale} Autocomplete options{Object.keys(locales)} ... / TablePagination count{2000} rowsPerPage{10} page{1} componentdiv onPageChange{() {}} / /ThemeProvider );示例特意选用TablePagination和Autocomplete因为二者恰好覆盖了 locale 中最直观的可见文本分页标签、加载/无选项提示。支持的语言环境清单mui/material/locale的导出清单以 index.ts 为准它逐一export *了各语言文件并额外导出utils/LocaleTextApi的类型。官方文档列出的受支持 locale 及对应的 BCP 47 语言标签、导入名如下LocaleBCP 47 language tagImport nameAmharicam-ETamETArabic (Egypt)ar-EGarEGArabic (Saudi Arabia)ar-SAarSAArabic (Sudan)ar-SDarSDArmenianhy-AMhyAMAzerbaijaniaz-AZazAZBanglabn-BDbnBDBulgarianbg-BGbgBGCatalanca-EScaESChinese (Hong Kong)zh-HKzhHKChinese (Simplified)zh-CNzhCNChinese (Taiwan)zh-TWzhTWCroatianhr-HRhrHRCzechcs-CZcsCZDanishda-DKdaDKDutchnl-NLnlNLEnglish (United States)en-USenUSEstonianet-EEetEEFinnishfi-FIfiFIFrenchfr-FRfrFRGermande-DEdeDEGreekel-GRelGRHebrewhe-ILheILHindihi-INhiINHungarianhu-HUhuHUIcelandicis-ISisISIndonesianid-IDidIDItalianit-ITitITJapaneseja-JPjaJPKhmerkh-KHkhKHKazakhkk-KZkkKZKoreanko-KRkoKRKurdish (Central)ku-CKBkuCKBMacedonianmk-MKmkMKMyanmarmy-MYmyMYMalayms-MSmsMSNepaline-NPneNPNorwegian (bokmål)nb-NOnbNONorwegian (nynorsk)nn-NOnnNOPashto (Afghanistan)ps-AFpsAFPersianfa-IRfaIRPolishpl-PLplPLPortuguesept-PTptPTPortuguese (Brazil)pt-BRptBRRomanianro-ROroRORussianru-RUruRUSerbiansr-RSsrRSSinhalesesi-LKsiLKSlovaksk-SKskSKSpanishes-ESesESSwedishsv-SEsvSEThaith-THthTHTurkishtr-TRtrTRTagalogtl-TLtlTLUkrainianuk-UAukUAUrdu (Pakistan)ur-PKurPKVietnamesevi-VNviVN从源码结构看locale 目录 实际导出的语言文件共 59 个比上表多出beBY白俄罗斯语be-BY与kuLatn库尔德语拉丁拼写ku-Latn。若目标用户群需要这些变体可直接从mui/material/locale导入即使文档表格尚未列出。创建自定义翻译与回贡流程如果需要支持的语言不在上表中或者想微调现有文案例如把英文文本改写成品牌化措辞官方给出的做法是找到 locale 源码目录 中与你目标语言最接近的文件如自定义德语变体可基于deDE.ts将该文件复制到你的项目内按需修改defaultProps中的文本从项目内的副本导入并传给createTheme例如import { myCustomLocale } from ./locales/myLocale;。由于 locale 对象只是普通的components.{name}.defaultProps结构见 LocaleTextApi.ts 的Localization接口你甚至可以只覆盖部分组件的文本其余字段留空即可——深合并会保留deepmerge后来自其他来源的内容。文档同时邀请开发者通过 pull request 回贡新翻译但给出了明确的取舍标准Material UI 的目标是覆盖使用人数最多的 100 种语言环境因此使用频率不高的语言文档举例仅约 250 万母语者的gl-ES加利西亚语可能不会被合入。RTL从右到左语言支持阿拉伯语arEG、arSA、arSD、波斯语faIR、希伯来语heIL、库尔德语kuCKB等从右到左书写的语言是受支持的。但仅声明 RTL locale 文本并不改变布局方向——布局层面的镜像、字体间距、图标翻转等需要在文档层面另行处理官方指引见 RTL 定制指南其要点是通过dirrtl与对应的样式适配使界面从右向左排布。实践时通常二者组合主题中传入 RTL 语言 locale 按 RTL 指南调整应用容器方向。小结配置链路与适用范围把整条链路串起来即createTheme(options, locale)将 locale 深合并进主题 → 各组件通过getThemeProps读取theme.components[名称].defaultProps获得本地化默认文本 → 业务显式 props 始终可覆盖 locale 文案。该机制仅覆盖mui/material核心组件MUI X 的 Data Grid、Pickers 等产品线各有独立的本地化配置入口不可混用。所有语言文件的完整源码均可在 packages/mui-material/src/locale/ 下按语言文件逐一查阅。【免费下载链接】material-uiMaterial UI: Comprehensive React component library that implements Googles Material Design. Free forever.项目地址: https://gitcode.com/GitHub_Trending/ma/material-ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Material UI 本地化完全指南：createTheme Locale 配置、57 种语言支持、自定义翻译与 RTL
Material UI 本地化完全指南createTheme Locale 配置、57 种语言支持、自定义翻译与 RTL【免费下载链接】material-uiMaterial UI: Comprehensive React component library that implements Googles Material Design. Free forever.项目地址: https://gitcode.com/GitHub_Trending/ma/material-ui本篇技术指南基于 Material UIMUI官方文档 Localization 展开系统讲解如何为基于mui/material的 React 应用配置非默认语言从使用createTheme全局注入 locale 文本、理解 locale 对象内部结构与defaultProps生效链路到创建自定义翻译、处理阿拉伯语等 RTL 语言。读完本文你可以独立完成多语言应用搭建、为组件文本做定制覆盖并理解本地化文本在源码层面的具体落地方式。什么是 Material UI 的本地化本地化Localization又称 l10n指将产品或内容适配到特定区域locale或市场的过程。Material UI 的默认语言环境是英语美国en-US。当你的应用面向其他语言用户时只需在主题中声明对应的 locale 对象组件内置的用户可见文本分页、评分、自动完成、面包屑、警告提示等即会切换为对应语言的文案。需要特别说明Data Grid 与 Data Grid Pro属于 MUI X 产品线它们拥有独立的本地化体系不适用本文介绍的mui/material/locale配置方式需要按 MUI X 文档单独配置。通过 createTheme 全局配置 locale 文本官方推荐的方式是把 locale 对象作为createTheme的第二个参数传入从而把本地化文本配置应用到整个主题树中import { createTheme, ThemeProvider } from mui/material/styles; import { zhCN } from mui/material/locale; const theme createTheme( { palette: { primary: { main: #1976d2 }, }, }, zhCN, ); ThemeProvider theme{theme} App / /ThemeProvider;其中zhCN是简体中文 locale从mui/material/locale命名空间导入。导入后ThemeProvider包裹的整棵组件树内所有受本地化影响的组件文本都会使用中文。源码机制第二个参数是如何进入主题的locale 对象并非特殊 API而是走主题的通用深层合并通道。从 createTheme 的签名createTheme(options, ...args)可以看出所有额外的实参都会传给createThemeNoVars在那里执行// packages/mui-material/src/styles/createThemeNoVars.jsL117-L118 muiTheme deepmerge(muiTheme, other); muiTheme args.reduce((acc, argument) deepmerge(acc, argument), muiTheme);也就是说zhCN会被整体deepmerge进主题对象。观察 zhCN.ts 可以发现locale 对象的顶层结构只有一个components键其下按组件名挂defaultProps。例如// packages/mui-material/src/locale/zhCN.ts节选 export const zhCN: Localization { components: { MuiTablePagination: { defaultProps: { getItemAriaLabel: (type) { if (type first) return 第一页; if (type last) return 最后一页; if (type next) return 下一页; return 上一页; }, labelRowsPerPage: 每页行数:, labelDisplayedRows: ({ from, to, count }) 第 ${formatNumber(from)} 条到第 ${formatNumber(to)} 条${count ! -1 ? 共 ${formatNumber(count)} 条 : 至少 ${formatNumber(to)} 条}, }, }, // MuiRating、MuiAutocomplete、MuiAlert、MuiPagination、MuiBreadcrumbs ... }, };这些defaultProps之所以能生效是因为组件渲染时通过useThemeProps/getThemeProps从主题中读取theme.components[组件名].defaultProps并与用户传入的 props 做解析。核心实现在 getThemeProps.tsconst { theme, name, props } params; if (!theme || !theme.components || !theme.components[name] || !theme.components[name].defaultProps) { return props; } return resolveProps(theme.components[name].defaultProps, props);resolveProps遵循显式 props 优先于 defaultProps的解析规则。因此本地化只提供组件的默认文案业务侧任何显式传入的 prop例如给TablePagination传自定义labelDisplayedRows都会覆盖 locale 提供的文本——这为整体换语言 个别组件定制的组合使用留出了空间。locale 对象的结构Localization 接口所有 locale 文件都实现同一个类型契约定义在 LocaleTextApi.tsexport interface Localization { components?: { MuiAlert?: { defaultProps: PickComponentsPropsList[MuiAlert], closeText }; MuiBreadcrumbs?: { defaultProps: PickComponentsPropsList[MuiBreadcrumbs], expandText }; MuiTablePagination?:{ defaultProps: Pick..., labelRowsPerPage | labelDisplayedRows | getItemAriaLabel }; MuiRating?: { defaultProps: Pick..., emptyLabelText | getLabelText }; MuiAutocomplete?: { defaultProps: Pick..., clearText | closeText | loadingText | noOptionsText | openText }; MuiPagination?: { defaultProps: Pick..., aria-label | getItemAriaLabel }; }; }这份类型说明了本地化影响的组件与可翻译的文本位点Alert的关闭文本、Breadcrumbs的展开文本、TablePagination的每页行数/显示行数标签与按钮 aria-label、Rating的评分标签与空值标签、Autocomplete的清空/关闭/加载/无选项/打开提示文本以及Pagination的导航 aria-label 与单项 aria-label。值得注意的是源码注释核心包不依赖mui/lab因此MuiPagination的 props 是内联复制定义的而非引用ComponentsPropsList这解释了为什么Pagination的defaultProps只含aria-label与getItemAriaLabel两项。locale 中的数字格式化还依赖 buildFormatNumber它以Intl.NumberFormat按目标区域如zh-CN生成格式化器对非有限值或运行环境不支持Intl时优雅降级为String(value)保证 SSR 与老旧环境的健壮性。动态切换语言的官方示例文档中的交互示例 Locales.js 演示了运行时按用户选择切换语言用Autocomplete列出Object.keys(locales)作为可选项选中后用createTheme(theme, locales[locale])重建主题并包一层新的ThemeProviderimport * as locales from mui/material/locale; const themeWithLocale React.useMemo( () createTheme(theme, locales[locale]), [locale, theme], ); return ( ThemeProvider theme{themeWithLocale} Autocomplete options{Object.keys(locales)} ... / TablePagination count{2000} rowsPerPage{10} page{1} componentdiv onPageChange{() {}} / /ThemeProvider );示例特意选用TablePagination和Autocomplete因为二者恰好覆盖了 locale 中最直观的可见文本分页标签、加载/无选项提示。支持的语言环境清单mui/material/locale的导出清单以 index.ts 为准它逐一export *了各语言文件并额外导出utils/LocaleTextApi的类型。官方文档列出的受支持 locale 及对应的 BCP 47 语言标签、导入名如下LocaleBCP 47 language tagImport nameAmharicam-ETamETArabic (Egypt)ar-EGarEGArabic (Saudi Arabia)ar-SAarSAArabic (Sudan)ar-SDarSDArmenianhy-AMhyAMAzerbaijaniaz-AZazAZBanglabn-BDbnBDBulgarianbg-BGbgBGCatalanca-EScaESChinese (Hong Kong)zh-HKzhHKChinese (Simplified)zh-CNzhCNChinese (Taiwan)zh-TWzhTWCroatianhr-HRhrHRCzechcs-CZcsCZDanishda-DKdaDKDutchnl-NLnlNLEnglish (United States)en-USenUSEstonianet-EEetEEFinnishfi-FIfiFIFrenchfr-FRfrFRGermande-DEdeDEGreekel-GRelGRHebrewhe-ILheILHindihi-INhiINHungarianhu-HUhuHUIcelandicis-ISisISIndonesianid-IDidIDItalianit-ITitITJapaneseja-JPjaJPKhmerkh-KHkhKHKazakhkk-KZkkKZKoreanko-KRkoKRKurdish (Central)ku-CKBkuCKBMacedonianmk-MKmkMKMyanmarmy-MYmyMYMalayms-MSmsMSNepaline-NPneNPNorwegian (bokmål)nb-NOnbNONorwegian (nynorsk)nn-NOnnNOPashto (Afghanistan)ps-AFpsAFPersianfa-IRfaIRPolishpl-PLplPLPortuguesept-PTptPTPortuguese (Brazil)pt-BRptBRRomanianro-ROroRORussianru-RUruRUSerbiansr-RSsrRSSinhalesesi-LKsiLKSlovaksk-SKskSKSpanishes-ESesESSwedishsv-SEsvSEThaith-THthTHTurkishtr-TRtrTRTagalogtl-TLtlTLUkrainianuk-UAukUAUrdu (Pakistan)ur-PKurPKVietnamesevi-VNviVN从源码结构看locale 目录 实际导出的语言文件共 59 个比上表多出beBY白俄罗斯语be-BY与kuLatn库尔德语拉丁拼写ku-Latn。若目标用户群需要这些变体可直接从mui/material/locale导入即使文档表格尚未列出。创建自定义翻译与回贡流程如果需要支持的语言不在上表中或者想微调现有文案例如把英文文本改写成品牌化措辞官方给出的做法是找到 locale 源码目录 中与你目标语言最接近的文件如自定义德语变体可基于deDE.ts将该文件复制到你的项目内按需修改defaultProps中的文本从项目内的副本导入并传给createTheme例如import { myCustomLocale } from ./locales/myLocale;。由于 locale 对象只是普通的components.{name}.defaultProps结构见 LocaleTextApi.ts 的Localization接口你甚至可以只覆盖部分组件的文本其余字段留空即可——深合并会保留deepmerge后来自其他来源的内容。文档同时邀请开发者通过 pull request 回贡新翻译但给出了明确的取舍标准Material UI 的目标是覆盖使用人数最多的 100 种语言环境因此使用频率不高的语言文档举例仅约 250 万母语者的gl-ES加利西亚语可能不会被合入。RTL从右到左语言支持阿拉伯语arEG、arSA、arSD、波斯语faIR、希伯来语heIL、库尔德语kuCKB等从右到左书写的语言是受支持的。但仅声明 RTL locale 文本并不改变布局方向——布局层面的镜像、字体间距、图标翻转等需要在文档层面另行处理官方指引见 RTL 定制指南其要点是通过dirrtl与对应的样式适配使界面从右向左排布。实践时通常二者组合主题中传入 RTL 语言 locale 按 RTL 指南调整应用容器方向。小结配置链路与适用范围把整条链路串起来即createTheme(options, locale)将 locale 深合并进主题 → 各组件通过getThemeProps读取theme.components[名称].defaultProps获得本地化默认文本 → 业务显式 props 始终可覆盖 locale 文案。该机制仅覆盖mui/material核心组件MUI X 的 Data Grid、Pickers 等产品线各有独立的本地化配置入口不可混用。所有语言文件的完整源码均可在 packages/mui-material/src/locale/ 下按语言文件逐一查阅。【免费下载链接】material-uiMaterial UI: Comprehensive React component library that implements Googles Material Design. Free forever.项目地址: https://gitcode.com/GitHub_Trending/ma/material-ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考