i18n

i18n 中间件为 Flame 实例提供应用本地化服务。

你可以在 GitHub 上阅读该中间件的源码或通过 pkg.go.dev 查看 API 文档。

下载安装

go get github.com/flamego/i18n

用法示例

i18n.I18n 需要配合 i18n.Options 来初始化基于 go-i18n/i18n 实现的应用本地化引擎。

默认情况下，本地化文件都需要被存放在 "locales" 目录内，并以 locale_%s.ini 的格式对每个文件命名，其中 %s 代指 IETF BCP 47 规范所定义的语言标签，例如 "en-US"、"zh-CN"。

使用本地文件

$ tree .
.
├── locales
│   ├── locale_en-US.ini
│   └── locale_zh-CN.ini
├── go.mod
├── go.sum
└── main.go

package main

import (
	"github.com/flamego/flamego"
	"github.com/flamego/i18n"
)

func main() {
	f := flamego.Classic()
	f.Use(i18n.I18n(
		i18n.Options{
			Languages: []i18n.Language{
				{Name: "en-US", Description: "English"},
				{Name: "zh-CN", Description: "简体中文"},
			},
		},
	))
	f.Get("/", func(l i18n.Locale) string {
		return l.Translate("greeting")
	})
	f.Run()
}

greeting = How are you?

greeting = 你好吗？

使用 embed.FS

$ tree .
.
├── locales
│   ├── embed.go
│   ├── locale_en-US.ini
│   └── locale_zh-CN.ini
├── go.mod
├── go.sum
└── main.go

package main

import (
	"net/http"

	"github.com/flamego/flamego"
	"github.com/flamego/i18n"

	"main/locales"
)

func main() {
	f := flamego.Classic()
	f.Use(i18n.I18n(
		i18n.Options{
			FileSystem: http.FS(locales.Locales),
			Languages: []i18n.Language{
				{Name: "en-US", Description: "English"},
				{Name: "zh-CN", Description: "简体中文"},
			},
		},
	))
	f.Get("/", func(l i18n.Locale) string {
		return l.Translate("greeting")
	})
	f.Run()
}

package locales

import "embed"

//go:embed *.ini
var Locales embed.FS

greeting = How are you?

greeting = 你好吗？

注意

由于 Go embed 功能会编码文件的完整路径，因此需要将嵌入的代码放置于与本地化文件的相同目录下。

确定本地化语言

i18n 基于如下顺序决定展现的本地化语言：

1. 根据 URL 查询参数，默认为 lang，如 lang=en-US 表示使用 "英文（美国）"
2. 根据 Cookie，默认为 lang
3. 根据 Accept-Language 请求头
4. 如仍旧无法确定，则使用默认语言，默认配置下为 i18n.Options.Languages 的第一个元素。

无论本地化语言是通过何种方式确定的，该语言都会当作用户偏好被保存在 Cookie 中。