Skip to content
/ i18n Public

Minimal, flexible, simple to use/embed localization package.

License

Notifications You must be signed in to change notification settings

oblq/i18n

Repository files navigation

i18n

GitHub tag Build Status codecov Go Report Card GoDoc MIT license

i18n is a minimal, flexible, simple to use and simple to embed (in your own packages) localizations package.
It accept yaml, json or toml for both config and localizations files.

Installation

go get -u github.com/oblq/i18n/v2

Quickstart

Create a new instance:

package main

import (
	"github.com/oblq/i18n/v2"
	"golang.org/x/text/language"
)

func init() {
	// Optionally pass the config file path and nil config.
	// The config file can be in yaml, json or toml format.
	localizer, err := i18n.NewWithConfig(&i18n.Config{
            Locales: []string{
                language.English.String(), // "en"
                language.Italian.String(), // "it"
            },
            Path: "./example/localizations",
        })	
}

Localize a key:

localizer.T("en", "MY_KEY")

Localize a key using plural and multiple parameters:

# ./example/localizations/en.yaml file

WHOAMI: "I'm %s!"
localizer.TP("en", "WHOAMI", "i18n") // -> "I'm i18n!"

Automatically localize a key based on the http request, i18n will first look for the locale by the GetLocaleOverride func, then in cookies (language and/or lang keys), then in Accept-Language header:

func(w http.ResponseWriter, r *http.Request) {
	response := localizer.AutoT(r, "MY_KEY")
	w.WriteHeader(http.StatusOK)
	w.Write([]byte(response))
}

Optionally override the GetLocale func to automatically determine the locale to be used from http requests (using i18n.AutoT func), if an empty string is returned the default methods will be used anyway:

localizer.GetLocaleOverride = func(r *http.Request) string {
    user := MyCustomAuthLib.UserFromRequest(r)
    return user.Locale
}

Localized file server:

localizer.SetFileServer(
    map[string]http.Handler{
        language.English.String(): http.FileServer(http.Dir("./landing_en")),
        language.Italian.String(): http.FileServer(http.Dir("./landing_it")),
    }, 
)

mux.Handle("/", localizer)

Embed i18n in your package:

Use hardcoded localizations, they can be a json, yaml or toml string:

package main

import (
	"github.com/oblq/i18n/v2"
	"golang.org/x/text/language"
)

// keys
const (
	GEM = "GEM" // generic_error_message
)

var hardcodedLocs = map[string]map[string]string{
	language.English.String(): {
		GEM: "Something went wrong, please try again later %s",
	},
	language.Italian.String(): {
		GEM: "Qualcosa è andato storto, riprova più tardi %s",
	},
}

var localizer *i18n.I18n

func init() {
	localizer, err := i18n.NewWithConfig(&i18n.Config{
		Locales: []string{
			language.English.String(), // "en"
			language.Italian.String(), // "it"
		},
		Locs: hardcodedLocs,
	})
}

Middleware

package main

import (
	"net/http"
	
	"github.com/oblq/i18n/v2"
	"golang.org/x/text/language"
)

func init() {
	config := &i18n.Config{
		HTTPLookUpStrategy: []i18n.HTTPLocalePosition{
			{i18n.HTTPLocalePositionIDHeader, "Accept-Language"},
			{i18n.HTTPLocalePositionIDCookie, "locale"},
			{i18n.HTTPLocalePositionIDQuery, "lang"},
		},
		Locales: []string{
			language.Italian.String(), 
			language.English.String(),
		},
	}

	localizer, err := i18n.NewWithConfig(config)
	if err != nil {
		panic(err)
	}

	http.Handle("/this-is-my-locale", localizer.Middleware(http.HandlerFunc(getLocale)))
	http.ListenAndServe(":8080", nil)
}

func getLocale(w http.ResponseWriter, r *http.Request) {
	locale := r.Context().Value(i18n.MiddlewareContextLocaleKey)
	_, _ = w.Write([]byte(locale.(string)))
}

Vendored packages

Author

License

i18n is available under the MIT license. See the LICENSE file for more information.