国际化

Charturbo 的内置文本提供英语、韩语和简体中文三种语言。同一个语言区域（locale）设置既决定数字和日期格式（通过 Intl），也决定库自身输出的所有文本：无障碍摘要与键盘帮助、屏幕阅读器播报、数据表格的标题和表头、CSV 表头、默认提示框、图例与面包屑标签，以及默认系列名称。

你传入的文本（标题、系列名称、类别标签）按原样显示。

设置语言区域

import { Charturbo } from 'charturbo';

// 作用于整个 SDK 实例
const sdk = await Charturbo.create(canvas, { locale: 'ko-KR' });

// 之后修改：标签、提示框和无障碍文本会立即更新
sdk.setLocale('zh-CN');

// 按图表设置（折线图、面积图、K 线图、OHLC、直方图和组合图支持 `locale`）
sdk.renderLineChart(series, { locale: 'en-US' });

图表实际使用的语言区域按以下顺序确定：

1. 图表自身的 locale 选项
2. SDK 语言区域（create({ locale }) 或 setLocale）
3. 页面语言：<html lang="...">
4. 浏览器语言：navigator.language

提示

请为页面设置 <html lang>。屏幕阅读器会据此选择语音，Charturbo 也会自动跟随，无需额外代码。

支持的语言

语言区域标签	内置文本
en、en-* 以及所有没有内置文本的语言	英语
ko、ko-*	韩语
zh、zh-*（包括 zh-TW、zh-HK）	简体中文

数字和日期始终使用你给出的完整标签。因此 de-DE 会使用德语数字格式和英语文本，zh-TW 会使用台湾地区的数字格式和简体中文文本。如需繁体中文文本，请按下文方式注册。

import { CHARTURBO_LANGUAGES, resolveLanguage } from 'charturbo';

CHARTURBO_LANGUAGES;      // ['en', 'ko', 'zh-CN']
resolveLanguage('ko-KR'); // 'ko'
resolveLanguage('fr');    // 'en'

覆盖文本与添加语言

registerMessages(locale, messages) 可以覆盖任意内置文本，或在英语基础上添加新语言。文本按显示位置分组（common、a11y、core、box、combo、business、hierarchy、sparkline），只需传入要修改的键。

import { registerMessages } from 'charturbo';

// 全局修改一个中文词语
registerMessages('zh', { common: { total: '总计' } });

// 添加日语（未提供的键保持英语）
registerMessages('ja', {
  common: {
    total: '合計',
    value: '値',
    seriesName: (index) => `系列 ${index}`,
    position: (i, n) => `${n} 件中 ${i} 件目。`,
  },
});

sdk.setLocale('ja-JP');

对于 pt-BR 这样的标签，查找顺序为：内置语言（英语）→ 为 pt 注册的文本 → 为 pt-BR 注册的文本。

由于各语言的词序和复数形式不同，部分文本是函数。参数是已按图表语言区域格式化的字符串；需要复数形式时，还会传入原始数量：

registerMessages('en', {
  common: { points: (n, count) => `${count} ${n === 1 ? 'sample' : 'samples'}` },
});

注册的文本对之后渲染或刷新的图表生效。如需立即应用到当前图表，请调用 sdk.setLocale(sdk.getLocale())。

可以读取当前文本来查看所有键：

import { getMessages } from 'charturbo';

const m = getMessages('zh-CN');
console.log(Object.keys(m.a11y));

CharturboMessages 类型定义了所有分组和键，编辑器可以自动补全。

不翻译的内容

• 面向开发者的错误信息（Error、CharturboInitError）保持英语，便于搜索。
• 默认下载文件名（chart.png、chart.svg）。
• 数字格式中的单位符号（k、M、KB）。

示例网站与文档

示例网站和本文档同样提供三种语言。请使用每个页面顶部的语言菜单切换。

另请参阅

• 数字与日期格式
• 无障碍
• 核心概念