i18n

README

i18n

Usage

Download and install it:

go get github.com/gin-contrib/i18n

Import it in your code:

import ginI18n "github.com/gin-contrib/i18n"

Canonical example:

package main

import (
  "log"
  "net/http"

  ginI18n "github.com/gin-contrib/i18n"
  "github.com/gin-gonic/gin"
  "github.com/nicksnyder/go-i18n/v2/i18n"
)

func main() {
  // new gin engine
  gin.SetMode(gin.ReleaseMode)
  router := gin.New()

  // apply i18n middleware
  router.Use(ginI18n.Localize())

  router.GET("/", func(context *gin.Context) {
    context.String(http.StatusOK, ginI18n.MustGetMessage(context, "welcome"))
  })

  router.GET("/:name", func(context *gin.Context) {
    context.String(http.StatusOK, ginI18n.MustGetMessage(context, &i18n.LocalizeConfig{
      MessageID: "welcomeWithName",
      TemplateData: map[string]string{
        "name": context.Param("name"),
      },
    }))
  })

  if err := router.Run(":8080"); err != nil {
    log.Fatal(err)
  }
}

Customized Bundle

package main

import (
  "encoding/json"
  "log"
  "net/http"

  ginI18n "github.com/gin-contrib/i18n"
  "github.com/gin-gonic/gin"
  "github.com/nicksnyder/go-i18n/v2/i18n"
  "golang.org/x/text/language"
)

func main() {
  // new gin engine
  gin.SetMode(gin.ReleaseMode)
  router := gin.New()

  // apply i18n middleware
  router.Use(ginI18n.Localize(ginI18n.WithBundle(&ginI18n.BundleCfg{
    RootPath:         "./_example/localizeJSON",
    AcceptLanguage:   []language.Tag{language.German, language.English},
    DefaultLanguage:  language.English,
    UnmarshalFunc:    json.Unmarshal,
    FormatBundleFile: "json",
  })))

  router.GET("/", func(context *gin.Context) {
    context.String(http.StatusOK, ginI18n.MustGetMessage(context, "welcome"))
  })

  router.GET("/:name", func(context *gin.Context) {
    context.String(http.StatusOK, ginI18n.MustGetMessage(context, &i18n.LocalizeConfig{
      MessageID: "welcomeWithName",
      TemplateData: map[string]string{
        "name": context.Param("name"),
      },
    }))
  })

  if err := router.Run(":8080"); err != nil {
    log.Fatal(err)
  }
}

Customized Get Language Handler

package main

import (
  "log"
  "net/http"

  ginI18n "github.com/gin-contrib/i18n"
  "github.com/gin-gonic/gin"
  "github.com/nicksnyder/go-i18n/v2/i18n"
)

func main() {
  // new gin engine
  gin.SetMode(gin.ReleaseMode)
  router := gin.New()

  // apply i18n middleware
  router.Use(ginI18n.Localize(
    ginI18n.WithGetLngHandle(
      func(context *gin.Context, defaultLng string) string {
        lng := context.Query("lng")
        if lng == "" {
          return defaultLng
        }
        return lng
      },
    ),
  ))

  router.GET("/", func(context *gin.Context) {
    context.String(http.StatusOK, ginI18n.MustGetMessage(context, "welcome"))
  })

  router.GET("/:name", func(context *gin.Context) {
    context.String(http.StatusOK, ginI18n.MustGetMessage(context, &i18n.LocalizeConfig{
      MessageID: "welcomeWithName",
      TemplateData: map[string]string{
        "name": context.Param("name"),
      },
    }))
  })

  if err := router.Run(":8080"); err != nil {
    log.Fatal(err)
  }
}

License

This project is under MIT License. See the LICENSE file for the full license text.

Documentation

Index

• func GetMessage(context *gin.Context, param interface{}) (string, error)
• func Localize(opts ...Option) gin.HandlerFunc
• func MustGetMessage(context *gin.Context, param interface{}) string
• type BundleCfg
• type EmbedLoader
  • func (c *EmbedLoader) LoadMessage(path string) ([]byte, error)
• type GetLngHandler
• type GinI18n
  • func NewI18n(opts ...Option) GinI18n
• type GinI18nImpl
  • func (i *GinI18nImpl) GetMessage(param interface{}) (string, error)
  • func (i *GinI18nImpl) MustGetMessage(param interface{}) string
  • func (i *GinI18nImpl) SetBundle(cfg *BundleCfg)
  • func (i *GinI18nImpl) SetCurrentContext(ctx context.Context)
  • func (i *GinI18nImpl) SetGetLngHandler(handler GetLngHandler)
• type Loader
• type LoaderFunc
  • func (f LoaderFunc) LoadMessage(path string) ([]byte, error)
• type Option
  • func WithBundle(config *BundleCfg) Option
  • func WithGetLngHandle(handler GetLngHandler) Option

Functions

func GetMessage

func GetMessage(context *gin.Context, param interface{}) (string, error)

GetMessage get the i18n message

 param is one of these type: messageID, *i18n.LocalizeConfig
 Example:
	GetMessage(context, "hello") // messageID is hello
	GetMessage(context, &i18n.LocalizeConfig{
			MessageID: "welcomeWithName",
			TemplateData: map[string]string{
				"name": context.Param("name"),
			},
	})

func Localize

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

Localize ...

func MustGetMessage

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

MustGetMessage get the i18n message without error handling

  param is one of these type: messageID, *i18n.LocalizeConfig
  Example:
	MustGetMessage(context, "hello") // messageID is hello
	MustGetMessage(context, &i18n.LocalizeConfig{
			MessageID: "welcomeWithName",
			TemplateData: map[string]string{
				"name": context.Param("name"),
			},
	})

Types

type BundleCfg

type BundleCfg struct {
	DefaultLanguage  language.Tag
	FormatBundleFile string
	AcceptLanguage   []language.Tag
	RootPath         string
	UnmarshalFunc    i18n.UnmarshalFunc
	Loader           Loader
}

BundleCfg ...

type EmbedLoader

type EmbedLoader struct {
	FS embed.FS
}

func (*EmbedLoader) LoadMessage

func (c *EmbedLoader) LoadMessage(path string) ([]byte, error)

type GetLngHandler

type GetLngHandler = func(context *gin.Context, defaultLng string) string

GetLngHandler ...

type GinI18n

type GinI18n interface {
	GetMessage(param interface{}) (string, error)
	MustGetMessage(param interface{}) string
	SetCurrentContext(ctx context.Context)
	SetBundle(cfg *BundleCfg)
	SetGetLngHandler(handler GetLngHandler)
}

GinI18n ...

func NewI18n

func NewI18n(opts ...Option) GinI18n

NewI18n ...

type GinI18nImpl

type GinI18nImpl struct {
	// contains filtered or unexported fields
}

func (*GinI18nImpl) GetMessage

func (i *GinI18nImpl) GetMessage(param interface{}) (string, error)

getMessage get localize message by lng and messageID

func (*GinI18nImpl) MustGetMessage

func (i *GinI18nImpl) MustGetMessage(param interface{}) string

mustGetMessage ...

func (*GinI18nImpl) SetBundle

func (i *GinI18nImpl) SetBundle(cfg *BundleCfg)

func (*GinI18nImpl) SetCurrentContext

func (i *GinI18nImpl) SetCurrentContext(ctx context.Context)

func (*GinI18nImpl) SetGetLngHandler

func (i *GinI18nImpl) SetGetLngHandler(handler GetLngHandler)

type Loader

type Loader interface {
	LoadMessage(path string) ([]byte, error)
}

type LoaderFunc

type LoaderFunc func(path string) ([]byte, error)

func (LoaderFunc) LoadMessage

func (f LoaderFunc) LoadMessage(path string) ([]byte, error)

type Option

type Option func(GinI18n)

Option ...

func WithBundle

func WithBundle(config *BundleCfg) Option

WithBundle ...

func WithGetLngHandle

func WithGetLngHandle(handler GetLngHandler) Option

WithGetLngHandle ...