多语言配置

多语言配置的基本概念

ECharts的多语言配置功能允许开发者轻松实现图表在不同语言环境下的展示。核心原理是通过语言包机制，将界面文本内容与代码逻辑分离。ECharts内置了中文和英文两种语言包，同时支持开发者自定义扩展其他语言。

语言配置主要涉及以下几个部分：

• 轴标签、图例文本等静态内容的翻译
• 时间格式化、数字格式化的区域差异处理
• 工具提示、工具栏按钮等交互元素的本地化

内置语言包的使用

ECharts从5.0版本开始内置了中英文语言包，可以通过简单配置切换：

// 引入中文包（默认不需要显式引入）
import 'echarts/lib/lang/zh-CN'

// 引入英文包
import 'echarts/lib/lang/en'

// 初始化时指定语言
const chart = echarts.init(dom, null, {
  locale: 'en' // 或 'zh-CN'
})

当切换语言时，以下元素会自动更新：

1. 工具栏按钮文本（如'dataZoom'、'restore'）
2. 组件名称（如'series'、'xAxis'）
3. 提示框中的默认文本（如'series'、'value'）

自定义语言包开发

当需要支持非内置语言时，可以注册自定义语言包：

// 注册德语语言包
echarts.registerLocale('de-DE', {
  time: {
    month: [
      'Januar', 'Februar', 'März', 'April',
      'Mai', 'Juni', 'Juli', 'August',
      'September', 'Oktober', 'November', 'Dezember'
    ],
    monthAbbr: [
      'Jan', 'Feb', 'Mär', 'Apr',
      'Mai', 'Jun', 'Jul', 'Aug',
      'Sep', 'Okt', 'Nov', 'Dez'
    ]
  },
  legend: {
    selector: {
      all: 'Alle',
      inverse: 'Invers'
    }
  }
})

// 使用自定义语言
const chart = echarts.init(dom, null, {
  locale: 'de-DE'
})

完整语言包应包含以下典型字段：

interface LocaleOption {
  time: {
    month: string[]
    monthAbbr: string[]
    dayOfWeek: string[]
    dayOfWeekAbbr: string[]
  }
  legend: {
    selector: {
      all: string
      inverse: string
    }
  }
  toolbox: {
    brush: {
      title: {
        rect: string
        polygon: string
        lineX: string
        lineY: string
        keep: string
        clear: string
      }
    }
  }
  // 其他组件本地化字段...
}

动态语言切换实现

在实际应用中，往往需要支持运行时语言切换。以下是实现方案：

// 语言切换函数
function changeLanguage(lang) {
  // 销毁旧实例
  chart.dispose()
  
  // 重新初始化
  chart = echarts.init(dom, null, {
    locale: lang
  })
  
  // 重新设置选项
  chart.setOption(option)
}

// 配合Vue/React等框架的示例
// Vue示例
watch: {
  currentLang(newVal) {
    this.$nextTick(() => {
      this.chart.dispose()
      this.chart = echarts.init(this.$el, null, {
        locale: newVal
      })
      this.chart.setOption(this.option)
    })
  }
}

特殊格式的本地化处理

时间轴本地化

时间轴的星期、月份显示需要特殊处理：

option = {
  xAxis: {
    type: 'time',
    axisLabel: {
      formatter: function(value) {
        // 使用ECharts内置的日期格式化
        return echarts.format.formatTime('yyyy-MM-dd', value)
      }
    }
  }
}

数字格式化

不同地区的数字显示习惯不同：

// 使用ECDoF补充的数字格式化功能
import { format } from 'echarts/lib/export'

option = {
  series: [{
    label: {
      formatter: function(params) {
        return format.truncateText(params.name, 10) + ': ' + 
          format.addCommas(params.value)
      }
    }
  }]
}

多语言与主题的结合使用

语言配置可以与主题系统协同工作：

// 注册包含语言信息的主题
echarts.registerTheme('myTheme', {
  locale: 'ja-JP',
  textStyle: {
    fontFamily: 'Meiryo, sans-serif'
  }
})

// 初始化时同时指定主题和语言
const chart = echarts.init(dom, 'myTheme', {
  locale: 'ja-JP'
})

服务端渲染的注意事项

在SSR环境下，需要确保语言包在服务器端可用：

// Node.js端使用
const echarts = require('echarts/lib/echarts')
require('echarts/lib/lang/en')

// 在渲染函数中
function renderChart() {
  return `
    <script>
      echarts.registerLocale('en', ${JSON.stringify(require('echarts/lib/lang/en'))})
      const chart = echarts.init(null, null, {
        locale: 'en',
        ssr: true,
        width: 600,
        height: 400
      })
      chart.setOption(${JSON.stringify(option)})
      console.log(chart.renderToSVGString())
    </script>
  `
}

常见问题解决方案

语言包加载失败

// 安全加载方案
try {
  echarts.registerLocale('fr-FR', require('./locale/fr-FR'))
} catch (e) {
  console.warn('法语包加载失败，回退到英文')
  echarts.registerLocale('fr-FR', require('echarts/lib/lang/en'))
}

混合语言场景处理

当图表中需要显示多种语言时：

option = {
  title: {
    text: {
      'zh-CN': '销售数据',
      'en': 'Sales Data',
      'ja-JP': '販売データ'
    }[currentLang] || 'Sales Data'
  },
  tooltip: {
    formatter: function(params) {
      const i18n = {
        'zh-CN': '值',
        'en': 'Value',
        'ja-JP': '値'
      }
      return `${params.seriesName}: ${params.value} ${i18n[currentLang]}`
    }
  }
}

性能优化建议

1. 按需加载语言包：

// 动态导入语言包
async function loadLocale(lang) {
  const locale = await import(`echarts/lib/lang/${lang}`)
  echarts.registerLocale(lang, locale)
}

2. 缓存语言配置：

const localeCache = new Map()

function getChartOption(lang) {
  if (!localeCache.has(lang)) {
    const option = cloneDeep(baseOption)
    // 应用语言相关配置
    localeCache.set(lang, option)
  }
  return localeCache.get(lang)
}

测试与验证方法

确保多语言配置正确性的测试方案：

// 自动化测试示例
describe('ECharts多语言测试', () => {
  const languages = ['zh-CN', 'en', 'ja-JP']
  
  languages.forEach(lang => {
    it(`应正确渲染${lang}语言`, () => {
      const chart = initChart({ locale: lang })
      expect(chart.getOption().title.text).toMatchSnapshot()
    })
  })
})

// 视觉回归测试配置
const scenarios = languages.map(lang => ({
  label: `chart-${lang}`,
  url: `http://localhost:8080?lang=${lang}`,
  misMatchThreshold: 0.1
}))

扩展阅读：第三方集成

与i18n框架结合

// vue-i18n集成示例
import VueI18n from 'vue-i18n'

const i18n = new VueI18n({
  locale: 'zh-CN',
  messages: {
    'zh-CN': require('./locales/zh-CN.json'),
    'en': require('./locales/en.json')
  }
})

// 在ECharts配置中使用
option = {
  title: {
    text: i18n.t('chartTitle')
  },
  tooltip: {
    formatter: params => {
      return `${params.name}: ${i18n.t('value')} ${params.value}`
    }
  }
}

与React Intl集成

import { useIntl } from 'react-intl'

function ChartComponent() {
  const intl = useIntl()
  
  const option = {
    title: {
      text: intl.formatMessage({ id: 'chart.title' })
    },
    series: [{
      label: {
        formatter: params => intl.formatNumber(params.value)
      }
    }]
  }

  return <ReactECharts option={option} />
}