国际化

Hertz 提供了国际化 (i18n) 的中间件扩展。

Hertz 提供了国际化 (i18n) 的 中间件扩展 ，它参考了 Gin 的 实现 。

使用方法可参考如下 example

安装

go get github.com/hertz-contrib/i18n

示例代码

package main

import (
    "context"
    "github.com/cloudwego/hertz/pkg/app"
    "github.com/cloudwego/hertz/pkg/app/server"
    hertzI18n "github.com/hertz-contrib/i18n"
    "github.com/nicksnyder/go-i18n/v2/i18n"
)

func main() {
    h := server.New(server.WithHostPorts(":3000"))
    h.Use(hertzI18n.Localize())
    h.GET("/:name", func(c context.Context, ctx *app.RequestContext) {
        ctx.String(200, hertzI18n.MustGetMessage(c, &i18n.LocalizeConfig{
            MessageID: "welcomeWithName",
            TemplateData: map[string]string{
             "name": ctx.Param("name"),
          },
         }))
    })
	h.GET("/", func(c context.Context, ctx *app.RequestContext) {
        ctx.String(200, hertzI18n.MustGetMessage(c, "welcome"))
	})

      h.Spin()
}

配置

Localize

用于将 i18n 扩展集成进 hertz server

函数标签如下：

func Localize(opts ...Option) app.HandlerFunc

示例代码：

package main

import (
    "context"
    _ "embed"
    "time"

    "github.com/cloudwego/hertz/pkg/app"
    "github.com/cloudwego/hertz/pkg/app/server"
    hertzI18n "github.com/hertz-contrib/i18n"
    "github.com/nicksnyder/go-i18n/v2/i18n"
    "golang.org/x/text/language"
    "gopkg.in/yaml.v3"
)

func main() {
    h := server.New()
    h.Use(hertzI18n.Localize())
    h.GET("/:name", func(c context.Context, ctx *app.RequestContext) {
        ctx.String(200, hertzI18n.MustGetMessage(c, &i18n.LocalizeConfig{
            MessageID: "welcomeWithName",
            TemplateData: map[string]string{
                "name": ctx.Param("name"),
            },
        }))
    })
    h.GET("/", func(c context.Context, ctx *app.RequestContext) {
        ctx.String(200, hertzI18n.MustGetMessage(c, "welcome"))
    })

    h.Spin()
}

MustGetMessage

MustGetMessage 用于获取 i18n 信息，但不做错误处理。

函数签名如下：

func MustGetMessage(c context.Context, param interface{}) string

示例代码如下：

h.GET("/:name", func(c context.Context, ctx *app.RequestContext) {
	ctx.String(200, hertzI18n.MustGetMessage(c, &i18n.LocalizeConfig{
		MessageID: "welcomeWithName",
		TemplateData: map[string]string{
			"name": ctx.Param("name"),
		},
	}))
})
h.GET("/", func(c context.Context, ctx *app.RequestContext) {
	ctx.String(200, hertzI18n.MustGetMessage(c, "welcome"))
})

LocalizeConfig 配置项

该配置项移步 go-i18n 自行查看

WithBundle

WithBundle 用于将自定义配置加载进入中间件

函数标签如下：

func WithBundle(cfg *BundleCfg) Option

示例代码如下：

package main

import (
    "context"
    _ "embed"
    "time"

    "github.com/cloudwego/hertz/pkg/app"
    "github.com/cloudwego/hertz/pkg/app/server"
    hertzI18n "github.com/hertz-contrib/i18n"
    "github.com/nicksnyder/go-i18n/v2/i18n"
    "golang.org/x/text/language"
    "gopkg.in/yaml.v3"
)

func main() {
    h := server.New(
        server.WithHostPorts(":3000"),
        server.WithExitWaitTime(time.Second),
    )
    h.Use(hertzI18n.Localize(
        hertzI18n.WithBundle(&hertzI18n.BundleCfg{
            RootPath:         "./localize",
            AcceptLanguage:   []language.Tag{language.Chinese, language.English},
            DefaultLanguage:  language.Chinese,
            FormatBundleFile: "yaml",
            UnmarshalFunc:    yaml.Unmarshal,
        }),
    ))
    h.GET("/:name", func(c context.Context, ctx *app.RequestContext) {
        ctx.String(200, hertzI18n.MustGetMessage(c, &i18n.LocalizeConfig{
            MessageID: "welcomeWithName",
            TemplateData: map[string]string{
                "name": ctx.Param("name"),
            },
        }))
    })
    h.GET("/", func(c context.Context, ctx *app.RequestContext) {
        ctx.String(200, hertzI18n.MustGetMessage(c, "welcome"))
    })

    h.Spin()
}

配置项

配置项 类型 默认值 描述
DefaultLanguage language.Tag language.English 默认转换语言类型
FormatBundleFile string “yaml” 转换文件模板类型，例如：yaml, json
AcceptLanguage []language.Tag []language.Tag{defaultLanguage,language.Chinese} 接收转换类型
RootPath string defaultRootPath 模板文件目录
UnmarshalFunc i18n.UnmarshalFunc yaml.Unmarshal 模板文件解码函数，例如：yaml.Unmarshal
Loader Loader LoaderFunc(ioutil.ReadFile) 文件读取函数，例如 LoaderFunc(ioutil.ReadFile)

WithGetLangHandle

WithGetLangHandle 用于配置 i18n 模板触发条件，可以通过从参数，请求头中取出信息

函数标签如下：

func WithGetLangHandle(handler GetLangHandler)

示例代码如下：

func main() {
    h := server.New()
	h.Use(hertzI18n.Localize(
		hertzI18n.WithGetLangHandle(
			func(c context.Context, ctx *app.RequestContext, defaultLang string) string {
				lang := ctx.Query("lang")
				if lang == "" {
					return defaultLang
				}
				return lang
			},
		),
	))
	// ...
    h.Spin()
}

完整用法示例详见 i18n


最后修改 March 22, 2024 : docs: optimize hertz vd tag description (#995) (ee7bb09)