ECharts 多语言切换完全指南：从图表说中文到自定义语言包

ECharts 多语言切换完全指南：从图表说中文到自定义语言包

【免费下载链接】echartsApache ECharts is a powerful, interactive charting and data visualization library for browser项目地址: https://gitcode.com/GitHub_Trending/echa/echarts

做 ECharts 国际化的第一步，往往是被自己的图表"打脸"：给中文用户看的页面，时间轴上却飘着 January、February，工具栏的按钮也清一色英文。这种图表中文化显示的问题，其实不需要动配置里的 series，也不需要改任何数据——ECharts 多语言的核心就是一个locale参数加上一份语言包，下面按实际使用顺序把这套东西讲清楚。

注册语言包，3 行代码让图表说中文

每个语言包都是一个普通 JS 对象，文件加载后会自动调用echarts.registerLocale把自己注册进去。registerLocale就是 ECharts i18n 的入口：它把一份语言数据挂到全局，之后所有图表都能按名字取用。仓库的 i18n/ 目录里已经放好了几十种语言的现成文件，常用的比如 langZH.js（代码 'ZH'）、langEN.js（'EN'），还有日文 'JA' 等，按需引入即可。

初始化时，把语言代码传给init的第三个参数就能全局生效：

// 引入 i18n/langZH.js 后，初始化时指定 locale const chart = echarts.init(document.getElementById('main'), null, { locale: 'ZH' // 时间轴、图例、工具栏全部切换为中文 });

这就是最直接的 echarts locale 配置方式，写对这一行，大部分"图表里的英文"问题当场消失。

语言包里面到底装了哪些文案

打开任意语言文件看结构，四个命名空间分工明确：

• time：月份、星期，时间轴和 tooltip 默认用它渲染日期
• legend：图例上"全选 / 反选"这类按钮文案
• toolbox：数据视图、区域缩放、还原、保存为图片等工具栏按钮
• series.typeNames：每种图表类型的名称，aria 无障碍朗读时会用到

理解了这份清单，你就知道哪些文字会随语言自动变、哪些不会变——这也是后面排坑的伏笔。

运行中切换语言：setOption 改 locale

页面有语言切换按钮时，不需要销毁重建实例，setOption可以只更新 locale：

// 右上角放一个切换按钮 document.getElementById('switch').onclick = () => { chart.setOption({ locale: currentLang = 'EN' }); // 重新渲染，全部文案换语言 };

注意前提是目标语言包已注册过，否则切过去只会得到空白文案。对 ECharts 切换语言这件事来说，一次setOption就是全部工作量，代价只是一次重渲染。

自定义一个繁体中文语言包

内置 40 多种语言覆盖主流地区，但繁体中文这种"差一点点"的需求就没有现成的。这时候自己造一个包，照着 i18n/langZH.js 的结构翻译一遍即可，不必全量复制，缺失的部分会自动回落英文默认值：

const localeTW = { time: { month: ['一月', '二月', '三月', '四月', '五月', '六月', '七月', '八月', '九月', '十月', '十一月', '十二月'], monthAbbr: ['1月', '2月', '3月', '4月', '5月', '6月', '7月', '8月', '9月', '10月', '11月', '12月'] }, legend: { selector: { all: '全選', inverse: '反選' } } }; echarts.registerLocale('TW', localeTW); // 注册后任何图表都能写 locale: 'TW'

自定义语言包和内置语言走的是同一套注册机制，所以初始化或切换时对它一视同仁。

让时间格式跟着语言走

语言包里time.month决定的是"一月"还是 "January"，轴上默认渲染就会自动跟随。麻烦出现在你自己写了 formatter 的情况：模板字符串是你拼的，ECharts 不会替你翻译。这时在 formatter 里读当前语言、分支处理：

xAxis: { type: 'time', axisLabel: { formatter(value) { const lang = chart.getOption().locale; // 按当前语言选择不同的日期模板 return echarts.time.format( lang === 'ZH' ? 'yyyy年MM月dd日' : 'MMM dd, yyyy', value); } } }

原则一句话：让 ECharts 自己渲染的部分交给语言包，你手写文案的地方，自己读 locale 做判断。

多图表页面怎么统一管理语言状态

一个页面七八个图表，最忌挨个手改。把实例和当前语言收进一个小管理器，切换时批量下发：

const charts = []; // init 时把每个实例 push 进来 let currentLang = 'ZH'; function setLang(lang) { currentLang = lang; charts.forEach(c => c.setOption({ locale: lang })); // 一次遍历全部更新 }

语言状态只保存一份，所有图表都从这一份取值，不会出现"三个图中文、一个图英文"的尴尬。

踩过的几个坑，提前告诉你

切完语言还有英文残留？十有八九是你自定义的 formatter 或 graphic 组件里写死了文案。先全局搜一下硬编码字符串，再确认语言包加载顺序没把目标语言覆盖掉。

要做 RTL（阿拉伯语、希伯来语）？ECharts 画布内的内容不会自动镜像，常规做法是给图表容器加direction: rtl的 CSS，把外围布局翻过去，再配合 RTL 语言包处理文案。

想给官方加一种语言？拿 i18n/ 下任一语言文件当模板，翻译齐所有文案后向社区提 PR；如果只是自己用，registerLocale注册私有包就够了。

到这里，注册语言包、指定 locale、setOption切换、自定义语言包这四步已经闭环。剩下的活儿，就是去 i18n/ 目录挑一份现成文件，让你的图表跟着用户说同一种语言。

【免费下载链接】echartsApache ECharts is a powerful, interactive charting and data visualization library for browser项目地址: https://gitcode.com/GitHub_Trending/echa/echarts