i18n

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

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

下载安装

Go 语言的最低版本要求为 1.16

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 中。