深入解析 go-playground/locales:Go 语言基于 Unicode CLDR 的本地化与复数规则引擎
深入解析 go-playground/locales:Go 语言基于 Unicode CLDR 的本地化与复数规则引擎
导读
go-playground/locales 是一个从 Unicode CLDR 项目数据自动生成、覆盖全球数百种语言的 Go 本地化(i18n)工具包,可独立使用,也可嵌入 universal-translator 等国际化框架。本文以 vendor 目录下的 README 为主线,结合 rules.go 与 currency 包 的源码,带你掌握其日期时间、数字货币、复数规则三大核心能力,并理解其底层精度模型与接口设计,读完即可在项目中落地多语言格式化与复数判断。
一、项目定位与特性总览
go-playground/locales 是一个纯 Go 实现的 locale(区域设置)数据集。所有规则并非手工编写,而是由 Unicode CLDR Project(Common Locale Data Repository,通用区域数据仓库)的公开数据自动生成。这意味着任何语言数据的错误都应优先反馈给 CLDR 社区,待库重新生成时即可自动修复,而不是在 locale 文件中手工打补丁(手工改动会在下一次重新生成时被覆盖)。
它被设计为既可以独立使用,也可以嵌入任意 i18n 包中;官方主要配套 Universal Translator(该依赖同样 vendored 于本仓库 vendor/github.com/go-playground/universal-translator/),但并不绑定,完全可以单独引入。
在 Sliver 仓库的依赖清单中,该库以 github.com/go-playground/locales v0.14.1 的形式作为间接依赖(// indirect)被 vendored(见 go.mod),与 universal-translator v0.18.1 成对出现,用于为校验库提供本地化错误消息能力。
核心特性清单
- [x] 规则基于最新 CLDR 数据生成(生成时对应 CLDR v36.0.1)
- [x] 内置 Cardinal(基数)、Ordinal(序数)、Range(范围)三类复数规则
- [x] 内置月份(Month)、星期(Weekday)、时区(Timezone)翻译
- [x] 提供日期(Date)与时间(Time)格式化函数
- [x] 提供数字(Number)、货币(Currency)、记账(Accounting)、百分比(Percent)格式化函数
- [x] 目前仅支持"格里高利历"(Gregorian calendar),作者在 README 中坦言这是精力有限下的取舍
二、安装与依赖版本
作为 Go 模块,安装方式与其他库一致:
go get github.com/go-playground/locales
若使用 Go Modules,在 go.mod 的 require 块中声明即可,例如本仓库使用的版本为:
github.com/go-playground/locales v0.14.1 // indirect
github.com/go-playground/universal-translator v0.18.1 // indirect
安装后,每个语言/地区组合(如 en_CA、zh_CN、ja)都会以独立子包的形式存在,可直接按语言导入。同时附带的 currency 子包提供货币类型枚举,供货币格式化使用。
三、快速上手:en_CA 完整示例
README 给出了一个可以直接编译运行的完整示例(原文照录并加以注释)。它先构造一个位于多伦多时区的具体时间点,再通过 en_CA.New() 获得 locale 实例,逐一演示日期、时间、月份、星期、数字、货币、记账、百分比及复数规则的调用方式:
package main
import (
"fmt"
"time"
"github.com/go-playground/locales/currency"
"github.com/go-playground/locales/en_CA"
)
func main() {
loc, _ := time.LoadLocation("America/Toronto")
datetime := time.Date(2016, 02, 03, 9, 0, 1, 0, loc)
l := en_CA.New()
// Dates(日期:Full/Long/Medium/Short 四种粒度)
fmt.Println(l.FmtDateFull(datetime))
fmt.Println(l.FmtDateLong(datetime))
fmt.Println(l.FmtDateMedium(datetime))
fmt.Println(l.FmtDateShort(datetime))
// Times(时间:Full/Long/Medium/Short 四种粒度)
fmt.Println(l.FmtTimeFull(datetime))
fmt.Println(l.FmtTimeLong(datetime))
fmt.Println(l.FmtTimeMedium(datetime))
fmt.Println(l.FmtTimeShort(datetime))
// Months Wide(月份全称)
fmt.Println(l.MonthWide(time.January))
fmt.Println(l.MonthWide(time.February))
fmt.Println(l.MonthWide(time.March))
// ...
// Months Abbreviated(月份缩写)
fmt.Println(l.MonthAbbreviated(time.January))
fmt.Println(l.MonthAbbreviated(time.February))
fmt.Println(l.MonthAbbreviated(time.March))
// ...
// Months Narrow(月份窄体)
fmt.Println(l.MonthNarrow(time.January))
fmt.Println(l.MonthNarrow(time.February))
fmt.Println(l.MonthNarrow(time.March))
// ...
// Weekdays Wide(星期全称)
fmt.Println(l.WeekdayWide(time.Sunday))
fmt.Println(l.WeekdayWide(time.Monday))
fmt.Println(l.WeekdayWide(time.Tuesday))
// ...
// Weekdays Abbreviated(星期缩写)
fmt.Println(l.WeekdayAbbreviated(time.Sunday))
fmt.Println(l.WeekdayAbbreviated(time.Monday))
fmt.Println(l.WeekdayAbbreviated(time.Tuesday))
// ...
// Weekdays Short(星期短体)
fmt.Println(l.WeekdayShort(time.Sunday))
fmt.Println(l.WeekdayShort(time.Monday))
fmt.Println(l.WeekdayShort(time.Tuesday))
// ...
// Weekdays Narrow(星期窄体)
fmt.Println(l.WeekdayNarrow(time.Sunday))
fmt.Println(l.WeekdayNarrow(time.Monday))
fmt.Println(l.WeekdayNarrow(time.Tuesday))
// ...
var f64 float64
f64 = -10356.4523
// Number(数字格式化,2 为小数位精度)
fmt.Println(l.FmtNumber(f64, 2))
// Currency(货币格式化:加元 / 美元)
fmt.Println(l.FmtCurrency(f64, 2, currency.CAD))
fmt.Println(l.FmtCurrency(f64, 2, currency.USD))
// Accounting(记账格式:负数通常用括号表示)
fmt.Println(l.FmtAccounting(f64, 2, currency.CAD))
fmt.Println(l.FmtAccounting(f64, 2, currency.USD))
f64 = 78.12
// Percent(百分比格式化,注意:传入值本身已按百分数计)
fmt.Println(l.FmtPercent(f64, 0))
// Plural Rules for locale, so you know what rules you must cover
// 获取该语言需要覆盖的复数类别
fmt.Println(l.PluralsCardinal())
fmt.Println(l.PluralsOrdinal())
// Cardinal Plural Rules(基数复数规则)
fmt.Println(l.CardinalPluralRule(1, 0))
fmt.Println(l.CardinalPluralRule(1.0, 0))
fmt.Println(l.CardinalPluralRule(1.0, 1))
fmt.Println(l.CardinalPluralRule(3, 0))
// Ordinal Plural Rules(序数复数规则)
fmt.Println(l.OrdinalPluralRule(21, 0)) // 21st
fmt.Println(l.OrdinalPluralRule(22, 0)) // 22nd
fmt.Println(l.OrdinalPluralRule(33, 0)) // 33rd
fmt.Println(l.OrdinalPluralRule(34, 0)) // 34th
// Range Plural Rules(范围复数规则)
fmt.Println(l.RangePluralRule(1, 0, 1, 0)) // 1-1
fmt.Println(l.RangePluralRule(1, 0, 2, 0)) // 1-2
fmt.Println(l.RangePluralRule(5, 0, 8, 0)) // 5-8
}
3.1 为什么几乎所有返回值都是 []byte
README 特别说明:绝大多数返回类型是 []byte 而非 string。原因是这些结果经常需要拼接进更大的文本段落;若调用方原本就在向字节数组追加内容,[]byte 可以直接 append,避免一次额外的分配与拷贝。不需要时直接 string(...) 强制转换即可,语义完全等价。
3.2 三个参数约定
从示例中可以总结出格式化函数的统一参数风格:
| 函数 | 参数 | 说明 |
|---|---|---|
FmtNumber(num, v) |
num 数值,v 小数位精度 |
根据 v 同时处理整数与实数 |
FmtPercent(num, v) |
num 数值(已按百分数计),v 精度 |
传入 78.12 即表示 78.12%,而非 0.7812 |
FmtCurrency(num, v, c) |
num 数值,v 精度,c 货币类型 |
货币类型取自 currency 包枚举 |
FmtAccounting(num, v, c) |
同上 | 记账格式,负数常以括号呈现 |
CardinalPluralRule(num, v) |
num 数值,v 小数位精度 |
返回该数字对应的基数复数类别 |
RangePluralRule(n1, v1, n2, v2) |
区间两端数字及各自精度 | 返回范围对应的复数类别 |
四、源码级剖析:Translator 接口与复数规则模型
仓库中的 rules.go 定义了所有 locale 必须实现的 Translator 接口,是理解整个库设计的关键入口。
4.1 PluralRule 枚举:CLDR 定义的六类复数
type PluralRule int
const (
PluralRuleUnknown PluralRule = iota
PluralRuleZero // zero
PluralRuleOne // one - singular
PluralRuleTwo // two - dual
PluralRuleFew // few - paucal
PluralRuleMany // many - 也用于单独成类的分数
PluralRuleOther // other - 必备的通用复数形式,也用于仅有一种形式的语言
)
这六个类别完全对齐 CLDR 的复数分类规范:zero、one(单数)、two(双数)、few(少量)、many(大量,且当分数单独成类时也归入此类)、other(通用形式,所有语言都必须包含,若语言本身只有一种复数形式则全部落入 other)。注意不同语言覆盖的类别并不相同:例如英语基数复数只有 one 与 other,而阿拉伯语则有 zero、one、two、few、many、other 全部六类——所以 README 示例中调用 PluralsCardinal() / PluralsOrdinal() 先获取"该语言必须覆盖哪些类别",对正确实现翻译文案至关重要。
4.2 Translator 接口全景
从源码结构看,Translator 接口(见 rules.go)由三组方法构成:
- 调试/开发辅助:
Locale()返回 locale 标识;PluralsCardinal()、PluralsOrdinal()、PluralsRange()返回该 locale 支持的复数类别数组; - 复数判断:
CardinalPluralRule(num, v)、OrdinalPluralRule(num, v)、RangePluralRule(n1, v1, n2, v2)分别返回基数/序数/范围复数类别; - 翻译与格式化:月份与星期各有 Wide(全称)、Abbreviated(缩写)、Narrow(窄体)三档,另有 Short(星期专属短体);日期时间各有 Full/Long/Medium/Short 四档;数字与货币类包含
FmtNumber、FmtPercent、FmtCurrency、FmtAccounting。
每个具体语言包(如 en_CA)都是该接口的一个实现,因此替换语言只需换一个 New(),调用代码无需改动——这是整个库可插拔设计的根基。
4.3 精度参数 v 的由来:浮点陷阱
接口中所有复数判断函数都要求显式传入精度参数 v(可见小数位数),这并非冗余设计,而是为了规避 IEEE 754 浮点数误差。README 与源码注释(rules.go)给出了典型案例:
v := float64(3.141)
i := float64(int64(v))
fmt.Println(v - i) // 输出 0.14100000000000001 而非 0.141
如果不指定精度,库将无法可靠地还原用户意图中的小数位(例如 1.0 究竟该视为整数 1 还是带一位小数的 1.0,直接影响复数规则的判定结果)。因此调用方必须显式给出 v,库据此精确解析数字的 n / i / v / w / f / t 六个 CLDR 复数判定要素:
n:数字绝对值(含整数与小数);i:整数部分;v:可见小数位数(含末尾零);w:可见小数位数(不含末尾零);f:可见小数部分(含末尾零);t:可见小数部分(不含末尾零)。
4.4 辅助函数 W / F / T
rules.go 还导出了三个纯函数,供复数规则实现内部计算使用:
W(n, v):返回不含末尾零的可见小数位数(即 CLDR 要素 w);F(n, v):返回含末尾零的可见小数部分(要素 f);T(n, v):返回不含末尾零的可见小数部分(要素 t)。
三者都基于 strconv.FormatFloat 对小数部分做字符串化后再反向剔除末尾零,并通过"字符串由内部实数生成、必然合法"这一前提安全地忽略解析错误。
五、货币枚举:currency 包
FmtCurrency 与 FmtAccounting 需要第三个参数:货币类型。它由同仓库的 currency 包 提供,核心定义是一个基于 int 的 Type 枚举:
package currency
type Type int
const (
ADP Type = iota
AED
AFA
AFN
// ... 覆盖全球货币,含历史币种如 AFA、ALK、BRZ 等
CAD // 加元
USD // 美元
CNY // 人民币
EUR // 欧元
GBP // 英镑
// ...
)
从源码结构看,该枚举按字母序从 ADP(安道尔比塞塔)一路排列至 ZWL(津巴布韦元),既包含现行货币,也保留了大量已废止或替换的历史货币代码,适合处理历史数据场景。
六、数据修正机制与注意事项
6.1 遇到错误数据怎么办
README 给出两条修正确认路径:
- 向 CLDR 上游贡献:所有规则均从 Unicode CLDR Project 生成。若发现某语言数据有误,最优先的做法是向 CLDR 提交修正;下一次该库重新生成 locale 时修复会自动生效,且一劳永逸惠及所有使用者。
- 自行创建 locale 或加入生成例外:若时间紧迫无法等待上游,可以复制粘贴现有 locale 文件自行修改,并确保其符合
Translator接口;或者直接在 locale 生成代码中加入例外,待重新生成时修复得以保留。
6.2 严禁直接修改 locale 文件
README 明确警告:不要直接修改 locale 文件内部——这些文件是生成产物,在下次重新生成时必定被覆盖,手工改动将全部丢失。正确的做法只能走上述两条路径。
6.3 适用范围与限制
- 仅支持格里高利历,尚未覆盖其他历法(如农历、希伯来历、伊斯兰历),作者在 README 中坦言这是精力所限的取舍;
- 复数规则、翻译与格式化的数据准确性依赖上游 CLDR 数据质量;
- 在 Sliver 仓库中该库为间接依赖,若你的业务只是依赖某个框架间接使用它,通常无需直接 import locale 包;若要自定义校验错误消息的语言,则可直接引入对应 locale 子包并配合 universal-translator 使用。
七、总结
go-playground/locales 的价值在于:把 CLDR 这座"全球语言数据的维基百科"变成 Go 世界随手可用的代码——你不需要理解阿拉伯语的双数规则、俄语的少量规则或立陶宛语的范围规则,只需调用 CardinalPluralRule、FmtCurrency 等接口即可得到符合目标语言习惯的结果。本文对应的所有源码、接口定义与依赖声明,均可在本仓库的 vendor/github.com/go-playground/locales 目录下进一步查阅:
- README.md:官方功能说明与使用示例;
- rules.go:
Translator接口、PluralRule枚举与精度模型; - currency/currency.go:货币类型枚举;
- universal-translator 目录:官方推荐的配套 i18n 框架。