Go Web 应用国际化（i18n）完整方案小结：从 Locale 设置到 go-i18n 多语言站点

• 文档
• 教程

本章（第 10 章《国际化和本地化》）围绕 i18n 的三大核心问题——如何确定 locale、如何保存 locale 相关的资源、如何根据 locale 提取对应内容——给出了一个完整的 Go Web 国际化方案，并沉淀为开源库 go-i18n。读完本文，你将系统掌握为 Go Web 应用添加多语言支持的完整路径：从设置默认地区、本地化文本/时间/货币/视图资源，到用 go-i18n 管理多语言包并在模板中直接完成翻译，从而做到"只增加语言包、不改应用代码"即可支持新语言。本文是 10.4 小结 的展开，正文内容以第 10 章各小节（设置默认地区、本地化资源、国际化站点）为主体骨架，并结合 第 14.5 节多语言支持 的框架集成实现加以佐证。

一、本章脉络：i18n 是什么、要解决哪三个问题

国际化和本地化（Internationalization and Localization，通常用 i18n 和 L10N 表示）：国际化是将针对某个地区设计的程序进行重构，使它在更多地区可用；本地化则是在面向国际化的程序中增加对新地区的支持。目标很明确——同样的页面在不同语言环境下显示不同效果，应用在运行时根据请求来源的地域与语言呈现不同的用户界面（参见 10.0 章概述）。

在 Go 标准库不提供 i18n 支持的背景下，要构建一个完整的 i18n 方案，必须依次解决三个问题：

1. 如何确定 locale；
2. 如何保存与 locale 相关的字符串或其它信息（文本、时间日期、货币、图片、视图等）；
3. 如何根据 locale 提取字符串和其它相应的信息。

本章按此顺序组织为三小节：第一小节解决"如何设置正确的 locale"，第二小节解决"如何处理/存储与 locale 相关的资源"，第三小节解决"如何根据不同 locale 返回合适内容"。三小节合起来，就是一个可落地、可扩展的 Go i18n 方案。

二、核心回顾一：如何确定 Locale（设置默认地区）

Locale 的命名规范

Locale 是一组描述世界上某一特定区域文本格式和语言习惯的设置的集合，其名称通常由三部分组成：

• 第一部分（强制）：语言缩写，如en（英文）、zh（中文）；
• 第二部分（可选）：下划线后的国家说明符，用于区分讲同一种语言的不同国家，如en_US（美国英语）、en_UK（英国英语）；
• 第三部分（可选）：句点后的字符集说明符，如zh_CN.gb2312（中国、gb2312 字符集）。

Go 语言默认采用 UTF-8 编码集，因此本章实现 i18n 时不考虑第三部分，统一采用前两部分作为 i18n 标准的 locale 名。

实用提示：在 Linux 和 Solaris 系统中可用locale -a命令列举所有支持的地区名，观察其命名规范；BSD 等系统没有 locale 命令，地区信息存储在/usr/share/locale中。

方式一：通过域名设置 Locale

应用运行时按域名分级映射 locale，例如把www.asta.com作为英文站（默认站）、www.asta.cn作为中文站。整域名映射只需一个 map 或简单的判断逻辑：

if r.Host == "www.asta.com" { i18n.SetLocale("en") } else if r.Host == "www.asta.cn" { i18n.SetLocale("zh-CN") } else if r.Host == "www.asta.tw" { i18n.SetLocale("zh-TW") }

也可以按子域名切分设置，如en.asta.com表示英文站点、cn.asta.com表示中文站点：

prefix := strings.Split(r.Host, ".") if prefix[0] == "en" { i18n.SetLocale("en") } else if prefix[0] == "cn" { i18n.SetLocale("zh-CN") } else if prefix[0] == "tw" { i18n.SetLocale("zh-TW") }

域名方式的优点是：URL 一眼可辨、用户直观知道访问哪种语言站点、Go 中用 map 即可实现、有利于搜索引擎抓取（SEO）。缺点是域名成本高（每种语言一个域名，且统一名称的域名不一定申请得到），且不愿为每个站点单独本地化配置，所以实践中更多采用 URL 带参数的方式。

方式二：通过 URL 参数设置 Locale

最常用的做法是在 URL 里带参数，例如www.asta.com/hello?locale=zh或www.asta.com/zh/hello，然后设置地区：i18n.SetLocale(params["locale"])。

这种方式几乎拥有域名方式的全部优点，且采用 RESTful 风格、无需额外处理方法；代价是每个链接里都要携带locale参数，略显繁琐。缓解办法是写一个通用的 URL 生成函数，所有链接地址都经由该函数生成，并在函数内自动追加locale=params["locale"]。

若希望 URL 更 RESTful、更利于 SEO（如www.asta.com/en/books、www.asta.com/zh/books），可通过 router 直接提取 locale 路径段：

mux.Get("/:locale/books", listbook)

方式三：通过客户端信息设置 Locale

一些场景需要根据客户端信息（而非 URL）来设置 locale，主要来源有三类：

• Accept-Language 请求头：客户端请求时在 HTTP 头携带Accept-Language，据此设置地区：

AL := r.Header.Get("Accept-Language") if AL == "en" { i18n.SetLocale("en") } else if AL == "zh-CN" { i18n.SetLocale("zh-CN") } else if AL == "zh-TW" { i18n.SetLocale("zh-TW") }

实际应用中可能需要更严格的判断逻辑（如按权重解析多语言列表）。

• IP 地址：根据 IP 库把访问 IP 映射到国家地区，再据此设置 locale，例如当时常用的 GeoIP Lite Country 库，机制简单：查库 → 得到国家/地区 → 设置对应 locale。
• 用户 profile：让用户通过下拉菜单等方式主动选择 locale，将选择保存到其账号 profile 中；用户再次登录时，把该设置复写回 locale，保证该用户每次访问都基于自己先前选择的语言。

小结：设置 locale 有多种方式，应按需求选择，让用户以最熟悉的方式获得服务、提升友好性。

三、核心回顾二：如何保存与 Locale 相关的资源（本地化资源）

确定 locale 后，下一步是存储与 locale 对应的信息：文本、时间日期、货币值、图片、包含文件及视图等。本章将这些格式信息存储在 JSON 中，再按需取出展示（下文以中文、英文两种语言对比，存储文件为en.json与zh-CN.json）。

本地化文本消息

文本是本地化资源中数量最多、最常用的一类。最简单的方案是用map[string]map[string]string维护 key-value 关系，输出前从合适的 map 中取文本：

package main import "fmt" var locales map[string]map[string]string func main() { locales = make(map[string]map[string]string, 2) en := make(map[string]string, 10) en["pea"] = "pea" en["bean"] = "bean" locales["en"] = en cn := make(map[string]string, 10) cn["pea"] = "豌豆" cn["bean"] = "毛豆" locales["zh-CN"] = cn lang := "zh-CN" fmt.Println(msg(lang, "pea")) fmt.Println(msg(lang, "bean")) } func msg(locale, key string) string { if v, ok := locales[locale]; ok { if v2, ok := v[key]; ok { return v2 } } return "" }

把lang切换为en即可切换到英文。当文本中包含变量（如"I am 30 years old"对应中文"我今年30岁了"）时，可结合fmt.Printf实现带参数的翻译：

en["how old"] = "I am %d years old" cn["how old"] = "我今年%d岁了" fmt.Printf(msg(lang, "how old"), 30)

以上仅演示内部实现思路；实际数据存储在 JSON 中，通过json.Unmarshal填充到对应 map。

本地化日期和时间

同一时刻在不同时区、不同 locale 下，时间表示与格式都不同（例如中文环境可能显示2012年10月24日 星期三 23时11分13秒 CST，英文环境可能显示Wed Oct 24 23:11:13 CST 2012）。需要解决两个问题：时区问题与格式问题。

时区方面，$GOROOT/lib/time包中的timeinfo.zip含有 locale 对应的时区定义。先通过time.LoadLocation(name string)获取对应时区（如Asia/Shanghai、America/Chicago），再结合time.Now()得到本地化时间：

en["time_zone"] = "America/Chicago" cn["time_zone"] = "Asia/Shanghai" loc, _ := time.LoadLocation(msg(lang, "time_zone")) t := time.Now() t = t.In(loc) fmt.Println(t.Format(time.RFC3339))

格式方面，与文本处理方式类似，把格式串作为 key-value 存储，再自行实现%Y %m %d %H %M %S等占位符替换：

en["date_format"] = "%Y-%m-%d %H:%M:%S" cn["date_format"] = "%Y年%m月%d日 %H时%M分%S秒" fmt.Println(date(msg(lang, "date_format"), t)) func date(format string, t time.Time) string { year, month, day := t.Date() hour, min, sec := t.Clock() // 解析相应的 %Y %m %d %H %M %S 然后返回信息 // %Y 替换成 2012 // %m 替换成 10 // %d 替换成 24 }

本地化货币值

各地区货币表示不同，处理方式与日期类似——把格式串存入 key-value，再用fmt.Sprintf代入金额：

en["money"] = "USD %d" cn["money"] = "￥%d元" fmt.Println(money_format(msg(lang, "money"), 100)) func money_format(format string, money int64) string { return fmt.Sprintf(format, money) }

本地化视图和资源

不同 locale 可能需要展示不同视图及图片、css、js 等静态资源。做法是按 locale 组织文件目录：

views |--en //英文模板 | |--images //存储图片信息 | |--js //存储JS文件 | |--css //存储css文件 | index.tpl //用户首页 | login.tpl //登陆首页 |--zh-CN //中文模板 | |--images | |--js | |--css | index.tpl | login.tpl

渲染时把lang拼进模板路径，并把Lang传给模板：

s1, _ := template.ParseFiles("views/" + lang + "/index.tpl") VV.Lang = lang s1.Execute(os.Stdout, VV)

index.tpl内部的静态资源引用同样基于{{.Lang}}：

<!-- js文件 --> <script type="text/javascript" src="views/{{.Lang}}/js/jquery/jquery-1.8.0.min.js"></script> <!-- css文件 --> <link href="views/{{.Lang}}/css/bootstrap-responsive.min.css" rel="stylesheet"> <!-- 图片文件 --> <img src="views/{{.Lang}}/images/btn.png">

小结：本地化资源本质上都以 key-value 方式存储：文本直接输出；时间日期、货币先经fmt.Printf等格式化函数处理；视图与静态资源最简单——在路径中增加lang即可。这种结构非常便于扩展。

四、核心回顾三：如何构建国际化站点（多语言包管理与模板函数）

管理多个本地包

单语言只需一个配置文件；多语言则要设计目录组织，方便后续语言扩展。本章的组织方式是把 locale 相关文件放在config/locales下，例如同时支持中英文时放置en.json和zh.json：

# zh.json { "zh": { "submit": "提交", "create": "创建" } } # en.json { "en": { "submit": "Submit", "create": "Create" } }

加载与使用 go-i18n 包的方式如下：

Tr := i18n.NewLocale() Tr.LoadPath("config/locales")

fmt.Println(Tr.Translate("submit")) // 输出 Submit Tr.SetLocale("zh") fmt.Println(Tr.Translate("submit")) // 输出 "提交"

自动加载默认本地包

go-i18n 预加载了时间格式、货币格式等默认格式信息，用户可在自定义配置时改写这些默认值。其加载逻辑（loadDefaultTranslations）会遍历语言目录下的所有文件：目录则递归加载，文件则按文件名匹配 locale 后逐个解析：

func (il *IL) loadDefaultTranslations(dirPath string) error { dir, err := os.Open(dirPath) if err != nil { return err } defer dir.Close() names, err := dir.Readdirnames(-1) if err != nil { return err } for _, name := range names { fullPath := path.Join(dirPath, name) fi, err := os.Stat(fullPath) if err != nil { return err } if fi.IsDir() { if err := il.loadTranslations(fullPath); err != nil { return err } } else if locale := il.matchingLocaleFromFileName(name); locale != "" { file, err := os.Open(fullPath) if err != nil { return err } defer file.Close() if err := il.loadTranslation(file, locale); err != nil { return err } } } return nil }

默认配置文件按zh.json、en.json、en-US.json等命名，可不断扩展支持更多语言。当没有自定义时间信息时，可直接调用封装好的方法拿到本地化结果：

// locale=zh 的情况下，执行如下代码： fmt.Println(Tr.Time(time.Now())) // 输出：2009年1月08日 星期四 20:37:58 CST fmt.Println(Tr.Time(time.Now(), "long")) // 输出：2009年1月08日 fmt.Println(Tr.Money(11.11)) // 输出:￥11.11

模板 mapfunc：在模板层直接翻译

Tr.Translate、Tr.Time、Tr.Money等函数通常运行在逻辑层；若想在模板层直接调用，可借助 Go 模板的自定义函数机制（FuncMap）注册包装函数：

1. 文本信息：调用Tr.Translate，包装为I18nT并注册为T：

func I18nT(args ...interface{}) string { ok := false var s string if len(args) == 1 { s, ok = args[0].(string) } if !ok { s = fmt.Sprint(args...) } return Tr.Translate(s) } t.Funcs(template.FuncMap{"T": I18nT})

模板中使用：{{.V.Submit | T}}

2. 时间日期：调用Tr.Time，包装为I18nTimeDate并注册为TD：

func I18nTimeDate(args ...interface{}) string { ok := false var s string if len(args) == 1 { s, ok = args[0].(string) } if !ok { s = fmt.Sprint(args...) } return Tr.Time(s) } t.Funcs(template.FuncMap{"TD": I18nTimeDate})

模板中使用：{{.V.Now | TD}}

3. 货币信息：调用Tr.Money，包装为I18nMoney并注册为M：

func I18nMoney(args ...interface{}) string { ok := false var s string if len(args) == 1 { s, ok = args[0].(string) } if !ok { s = fmt.Sprint(args...) } return Tr.Money(s) } t.Funcs(template.FuncMap{"M": I18nMoney})

模板中使用：{{.V.Money | M}}

小结：通过自定义语言包可方便地实现多语言；默认情况下 go-i18n 会加载时间、货币等公共配置；借助模板函数（T/TD/M），在 Web 开发中可直接通过模板 pipeline 操作多语言包，无需在逻辑层反复转换。

五、框架层面的落地：go-i18n 与 beego 的集成

本章的方案不止停留在库层面，还在 第 14.5 节《多语言支持》 中集成进了 beego 框架。beego 中设置三个全局变量承载 i18n：

Translation i18n.IL Lang string // 设置语言包，zh、en LangPath string // 设置语言包所在位置

初始化多语言函数：

func InitLang() { beego.Translation = i18n.NewLocale() beego.Translation.LoadPath(beego.LangPath) beego.Translation.SetLocale(beego.Lang) }

并注册三个模板函数，便于在模板中直接翻译：

beegoTplFuncMap["Trans"] = i18n.I18nT beegoTplFuncMap["TransDate"] = i18n.I18nTimeDate beegoTplFuncMap["TransMoney"] = i18n.I18nMoney

使用方式为：先设置语言与语言包路径并初始化——

beego.Lang = "zh" beego.LangPath = "views/lang" beego.InitLang()

再在LangPath下放置zh.json、en.json等多语言包（结构与上节config/locales下的 JSON 一致）；随后既可在 controller 中调用翻译：

func (this *MainController) Get() { this.Data["create"] = beego.Translation.Translate("create") this.TplNames = "index.tpl" }

也可在模板中直接调用翻译函数：

// 直接文本翻译 {{.create | Trans}} // 时间翻译 {{.time | TransDate}} // 货币翻译 {{.money | TransMoney}}

可以看到，从库到框架的集成保持了完全一致的抽象：locale 的加载、切换、翻译三件套（NewLocale/LoadPath/SetLocale+Translate/Time/Money）与模板函数包装，是整章方案可复用的核心。

六、本章小结：go-i18n 库的价值与后续方向

通过这一章的学习，可以建立对 i18n 操作的完整认知：确定 locale（域名 / URL 参数 / 客户端信息）→ 存储 locale 资源（文本、时间日期、货币、视图，全部 key-value 化并 JSON 化）→ 按 locale 提取与渲染（逻辑层Translate/Time/Money，模板层T/TD/M）。三者闭环，即可支撑一个多语言版本的 Web 应用，让应用轻松实现国际化，且新增语言时只需增加语言包、无需修改应用代码。

作者依据本章内容实现的开源解决方案go-i18n正是这一方案的成品化：通过它可很方便地实现多语言版本的 Web 应用，使应用轻松完成国际化。该库采用"默认公共配置 + 自定义语言包覆盖"的加载模型，配合 beego 等框架的模板函数注册机制，形成了一条低成本的国际化接入路径。作者也在本章小结中提出：如果发现该开源库中的错误或缺失之处，欢迎参与到这个开源项目中来，共同推动该库向 Go 标准库的目标演进（这属于作者的项目愿景，而非已实现的现状）。

围绕 go-i18n 的更多细节，可继续阅读本章前三节：设置默认地区、本地化资源、国际化站点，以及框架集成示例 14.5 多语言支持；下一章将进入 错误处理、故障排除和测试。

• 文档
• 教程