README
¶
i18n
i18n is a simple internationalization library for Golang. It provides a way to translate strings into multiple languages. This library is wrapper for go-i18n with some additional features.
Table of Contents
Installation
go get -u github.com/ahmadfaizk/i18n
Features
- Support translation file in YAML, JSON, and TOML format
- Translation
- Context translation
- Parametrized translation
- Missing translation Fallback
- Custom extract language from Context
Usage
Create Translation File
# locales/en.yaml
hello: Hello
hello_name: Hello, {{.name}}
hello_name_age: Hello, {{.name}}. You are {{.age}} years old
# locales/id.yaml
hello: Halo
hello_name: Halo, {{.name}}
hello_name_age: Halo, {{.name}}. Kamu berumur {{.age}} tahun
Initialize i18n
import (
"github.com/ahmadfaizk/i18n"
"golang.org/x/text/language"
"gopkg.in/yaml.v3"
)
i18n.Init(language.English,
i18n.WithUnmarshalFunc("yaml", yaml.Unmarshal),
i18n.WithTranslationFile("locales/en.yaml", "locales/id.yaml"),
)
Translate your text
fmt.Println(i18n.T("hello"))
// Hello
fmt.Println(i18n.T("hello", i18n.Lang("id")))
// Halo
fmt.Println(i18n.T("hello_name", i18n.Param("name", "John")))
// Hello, John
fmt.Println(i18n.T("hello_name", i18n.Lang("id"), i18n.Param("name", "John")))
// Halo, John
fmt.Println(i18n.T("hello_name_age", i18n.M{"name": "John", "age": 20}))
// Hello, John. You are 20 years old
fmt.Println(i18n.T("hello_name_age", i18n.Lang("id"), i18n.M{"name": "John", "age": 20}))
// Halo, John. Kamu berumur 20 tahun
Examples
See examples/ for a variety of examples.
package main
import (
"github.com/ahmadfaizk/i18n"
"github.com/go-chi/chi/v5"
"golang.org/x/text/language"
"gopkg.in/yaml.v3"
"net/http"
)
func main() {
if err := i18n.Init(language.English,
i18n.WithUnmarshalFunc("yaml", yaml.Unmarshal),
i18n.WithTranslationFile("locale/en.yaml", "locale/id.yaml"),
); err != nil {
panic(err)
}
r := chi.NewRouter()
r.Use(i18n.Middleware)
r.Get("/hello", func(w http.ResponseWriter, r *http.Request) {
message := i18n.TCtx(r.Context(), "hello")
_, _ = w.Write([]byte(message))
})
r.Get("/hello/{name}", func(w http.ResponseWriter, r *http.Request) {
name := chi.URLParam(r, "name")
message := i18n.TCtx(r.Context(), "hello_name", i18n.M{"name": name})
_, _ = w.Write([]byte(message))
})
if err := http.ListenAndServe(":3000", r); err != nil {
panic(err)
}
}
curl http://localhost:3000/hello # Hello
curl http://localhost:3000/hello/John # Hello, John
curl -H "Accept-Language: id" http://localhost:3000/hello # Halo
curl -H "Accept-Language: id" http://localhost:3000/hello/John # Halo, John
Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
License
This project is licensed under the MIT License - see the LICENSE file for details
Documentation
¶
Overview ¶
Package i18n is a wrapper for go-i18n. It provides a simple API to localize your application.
Index ¶
- Variables
- func Get(id string, opts ...any) string
- func GetCtx(ctx context.Context, id string, opts ...any) string
- func GetLanguage(ctx context.Context) language.Tag
- func Init(language language.Tag, opts ...Option) error
- func Middleware(next http.Handler) http.Handler
- func NewContextWithLanguage(ctx context.Context, language string) context.Context
- func T(id string, opts ...any) string
- func TCtx(ctx context.Context, id string, opts ...any) string
- type LOption
- type LocalizeOption
- type Option
- func WithExtractLanguageFunc(extractLanguageFunc func(ctx context.Context) string) Option
- func WithMissingTranslationHandler(missingTranslationHandler func(id string, err error) string) Option
- func WithTranslationFSFile(fs embed.FS, paths ...string) Option
- func WithTranslationFile(paths ...string) Option
- func WithUnmarshalFunc(format string, unmarshalFunc i18n.UnmarshalFunc) Option
- type Params
Constants ¶
This section is empty.
Variables ¶
var (
ErrI18nNotInitialized = errors.New("i18n is not initialized")
)
Functions ¶
func Get ¶
Get returns the translated message for the given message id.
It uses the default language tag.
Example:
message := i18n.Get("hello", i18n.Params{"name": "John"})
func GetCtx ¶
GetCtx returns the translated message for the given message id.
It uses the language from the context. You can set the language to the context with i18n.Middleware. If the language is not found in the context, it uses the default language tag.
Example:
message := i18n.GetCtx(ctx, "hello", i18n.Params{"name": "John"})
func GetLanguage ¶
GetLanguage returns the language tag from the context.
If the language tag is not found, it returns the default language tag.
func Init ¶
Init initializes the i18n package. It must be called before any other function.
Example:
if err := i18n.Init(language.English,
i18n.WithUnmarshalFunc("yaml", yaml.Unmarshal),
i18n.WithMessageFilePaths("locales/en.yaml", "locales/id.yaml"),
) err != nil {
panic(err)
}
func Middleware ¶
Middleware is a middleware that sets the language to the context from the request.
It uses the Accept-Language header to get the language.
func NewContextWithLanguage ¶ added in v0.1.1
NewContextWithLanguage sets the language to the context.
You can use this function to set the language to the context manually.
Types ¶
type LOption ¶ added in v0.1.1
type LOption interface {
map[string]interface{} | LocalizeOption
}
type LocalizeOption ¶
type LocalizeOption func(*localizeConfig)
LocalizeOption is a function that configures the localizeConfig.
func Default ¶ added in v0.1.1
func Default(defaultMessage string) LocalizeOption
Default sets the default message for the message.
It is used when the message is not found.
Example:
i18n.T("hello", i18n.Default("Hello, {{.name}}!"), i18n.Param("name", "John")))
func Lang ¶
func Lang(language string) LocalizeOption
Lang sets the language for the message.
Example:
i18n.T("hello", i18n.Lang("id"))
func Param ¶
func Param(key string, value interface{}) LocalizeOption
Param set single value of template data for the message.
Example:
i18n.T("hello", i18n.Param("name", "John"))
type Option ¶
type Option func(*config)
Option is the option for the i18n package.
func WithExtractLanguageFunc ¶ added in v0.1.1
WithExtractLanguageFunc sets the language extract function for the middleware.
It is used to extract the language from the context.
func WithMissingTranslationHandler ¶
func WithMissingTranslationHandler(missingTranslationHandler func(id string, err error) string) Option
WithMissingTranslationHandler sets the missing translation handler for the bundle.
It is used to handle the missing translation. The default handler returns the message ID.
func WithTranslationFSFile ¶
WithTranslationFSFile sets the message file paths for the bundle.
It is similar to WithTranslationFile, but it uses embed.FS as file system.
func WithTranslationFile ¶
WithTranslationFile sets the message file paths for the bundle.
func WithUnmarshalFunc ¶
func WithUnmarshalFunc(format string, unmarshalFunc i18n.UnmarshalFunc) Option
WithUnmarshalFunc sets the unmarshal function for the bundle.
It is used to unmarshal the message file. You can use yaml.Unmarshal, json.Unmarshal, or any other unmarshal function.
Source Files
Directories