深入解析 go-playground/locales:Go 语言基于 Unicode CLDR 的本地化与复数规则引擎

原创2026-09-23 21:05:011,669 阅读
文章标签:网络安全

深入解析 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 给出两条修正确认路径:

  1. 向 CLDR 上游贡献:所有规则均从 Unicode CLDR Project 生成。若发现某语言数据有误,最优先的做法是向 CLDR 提交修正;下一次该库重新生成 locale 时修复会自动生效,且一劳永逸惠及所有使用者。
  2. 自行创建 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 目录下进一步查阅:

登录后查看全文
sliver