Skip to content

README.md

Latest commit

 

History

History
105 lines (80 loc) · 6.64 KB

README.md

File metadata and controls

105 lines (80 loc) · 6.64 KB
id i18n

I18n

Release Discord Test

go-i18n support for Fiber.

Compatible with Fiber v3.

Go version support

We only support the latest two versions of Go. Visit https://go.dev/doc/devel/release for more information.

Install

go get -u github.com/gofiber/fiber/v3
go get -u github.com/gofiber/contrib/v3/i18n

API

Name Signature Description
New New(config ...*i18n.Config) *i18n.I18n Create a reusable, thread-safe localization container.
(*I18n).Localize Localize(ctx fiber.Ctx, params interface{}) (string, error) Returns a localized message. params must be a message ID string or *goi18n.LocalizeConfig. Returns an error if the message is not found, the param type is unsupported, or params is nil.
(*I18n).MustLocalize MustLocalize(ctx fiber.Ctx, params interface{}) string Like Localize but panics on any error.

Types

Name Description
Loader Interface for loading message files. Implement LoadMessage(path string) ([]byte, error).
LoaderFunc Adapter to use a plain function as a Loader.
EmbedLoader Loader implementation backed by an embed.FS. Use with Go's //go:embed directive.

Config

Property Type Description Default
RootPath string The i18n template folder path. "./example/localize"
AcceptLanguages []language.Tag A collection of languages that can be processed. []language.Tag{language.Chinese, language.English}
FormatBundleFile string The type of the template file. "yaml"
DefaultLanguage language.Tag The default returned language type. language.English
Loader Loader The implementation of the Loader interface, which defines how to read the file. We provide both os.ReadFile and embed.FS.ReadFile. LoaderFunc(os.ReadFile)
UnmarshalFunc i18n.UnmarshalFunc The function used for decoding template files. yaml.Unmarshal
LangHandler func(ctx fiber.Ctx, defaultLang string) string Used to get the kind of language handled by fiber.Ctx and defaultLang. Retrieved from the request header Accept-Language or query parameter lang.

Example

package main

import (
    "log"

    contribi18n "github.com/gofiber/contrib/v3/i18n"
    "github.com/gofiber/fiber/v3"
    goi18n "github.com/nicksnyder/go-i18n/v2/i18n"
    "golang.org/x/text/language"
)

func main() {
    translator := contribi18n.New(&contribi18n.Config{
        RootPath:        "./example/localize",
        AcceptLanguages: []language.Tag{language.Chinese, language.English},
        DefaultLanguage: language.Chinese,
    })

    app := fiber.New()
    app.Get("/", func(c fiber.Ctx) error {
        localize, err := translator.Localize(c, "welcome")
        if err != nil {
            return c.Status(fiber.StatusInternalServerError).SendString(err.Error())
        }
        return c.SendString(localize)
    })
    app.Get("/:name", func(ctx fiber.Ctx) error {
        return ctx.SendString(translator.MustLocalize(ctx, &goi18n.LocalizeConfig{
            MessageID: "welcomeWithName",
            TemplateData: map[string]string{
                "name": ctx.Params("name"),
            },
        }))
    })
    log.Fatal(app.Listen(":3000"))
}

Migration from middleware usage

The package now exposes a global, thread-safe container instead of middleware. To migrate existing code:

  1. Remove any app.Use(i18n.New(...)) calls—the translator no longer registers middleware.
  2. Instantiate a shared translator during application startup with translator := i18n.New(...).
  3. Replace package-level calls such as i18n.Localize/i18n.MustLocalize with the respective methods on your translator (translator.Localize, translator.MustLocalize).
  4. Drop any manual interaction with ctx.Locals("i18n"); all state is managed inside the translator instance.

The translator instance is safe for concurrent use across handlers and reduces per-request allocations by reusing the same bundle and localizer map.