i18n

The i18n middleware provides internationalization and localization for Flame instances.

You can read source code of this middleware on GitHubi18n - 图1open in new window and API documentation on pkg.go.devi18n - 图2open in new window.

Installation

The minimum requirement of Go is 1.16.

  1. go get github.com/flamego/i18n

Usage examples

The i18n.I18ni18n - 图3open in new window is used in combination with i18n.Optionsi18n - 图4open in new window to bootstrap the localization engine, which is built upon the shining go-i18n/i18ni18n - 图5open in new window.

By default, the locale files should resides in the “locales” directory and be named in the format of locale_%s.ini, where %s is the IETF BCP 47 language tagi18n - 图6open in new window, e.g. “en-US”, “zh-CN”.

Using local files

  • Directory
  • main.go
  • locale_en-US.ini
  • locale_zh-CN.ini
  1. $ tree .
  2. .
  3. ├── locales
  4. │   ├── locale_en-US.ini
  5. │   └── locale_zh-CN.ini
  6. ├── go.mod
  7. ├── go.sum
  8. └── main.go
  1. package main
  3. import (
  4.     "github.com/flamego/flamego"
  5.     "github.com/flamego/i18n"
  6. )
  8. func main() {
  9.     f := flamego.Classic()
  10.     f.Use(i18n.I18n(
  11.         i18n.Options{
  12.             Languages: []i18n.Language{
  13.                 {Name: "en-US", Description: "English"},
  14.                 {Name: "zh-CN", Description: "简体中文"},
  15.             },
  16.         },
  17.     ))
  18.     f.Get("/", func(l i18n.Locale) string {
  19.         return l.Translate("greeting")
  20.     })
  21.     f.Run()
  22. }
  1. greeting = How are you?
  1. greeting = 你好吗？

Using the embed.FS

  • Directory
  • main.go
  • embed.go
  • locale_en-US.ini
  • locale_zh-CN.ini
  1. $ tree .
  2. .
  3. ├── locales
  4. │   ├── embed.go
  5. │   ├── locale_en-US.ini
  6. │   └── locale_zh-CN.ini
  7. ├── go.mod
  8. ├── go.sum
  9. └── main.go
  1. package main
  3. import (
  4.     "net/http"
  6.     "github.com/flamego/flamego"
  7.     "github.com/flamego/i18n"
  9.     "main/locales"
  10. )
  12. func main() {
  13.     f := flamego.Classic()
  14.     f.Use(i18n.I18n(
  15.         i18n.Options{
  16.             FileSystem: http.FS(locales.Locales),
  17.             Languages: []i18n.Language{
  18.                 {Name: "en-US", Description: "English"},
  19.                 {Name: "zh-CN", Description: "简体中文"},
  20.             },
  21.         },
  22.     ))
  23.     f.Get("/", func(l i18n.Locale) string {
  24.         return l.Translate("greeting")
  25.     })
  26.     f.Run()
  27. }
  1. package locales
  3. import "embed"
  5. //go:embed *.ini
  6. var Locales embed.FS
  1. greeting = How are you?
  1. greeting = 你好吗？

WARNING

Because the Go embed encodes the entire path (i.e. including parent directories), the embedding should happen within the same directory as locale files.

Determine the language

The i18n middleware uses following technique to determine which language to use for translation:

  1. Look at the URL query parameter, by default it is lang, e.g. lang=en-US would force translation in “English (Unitied Stats)”.
  2. Look at the cookie value, by default it’s the value of lang.
  3. Look at the Accept-Language request header.
  4. Finally, fall back to the default language, which by default is the first language specified as the i18n.Options.Languages.

Regardless of how the language was determined, the cookie value is updated for saving preference.