README
¶
i18n 
Package i18n provides internationalization utilities.
Installing
-
Get package:
go get -u github.com/gowww/i18n -
Import it in your code with dependencies:
import ( "github.com/gowww/i18n" "golang.org/x/text/language" )
Usage
Make the Locales (string to string, for each language):
locales := i18n.Locales{
language.English: {
"hello": "Hello!",
},
language.French: {
"hello": "Bonjour !",
},
}
You're ready to make a handler with these locales, the default locale and the request parsers (matching the client language) you want to use.
Inside a handler, use RequestTranslator to get the translator containing the best locale for client.
Use Translator.T, Translator.THTML, Translator.Tn or Translator.TnHTML to retrieve the translation from a key.
i18n.RequestTranslator(r).T("hello")
So, to wrap an http.Handler, use Handle:
mux := http.NewServeMux()
mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
rt := i18n.RequestTranslator(r)
fmt.Fprint(w, rt.T("hello"))
})
http.ListenAndServe(":8080", i18n.Handle(mux, locales, language.English, i18n.ParseAcceptLanguage))
To wrap an http.HandlerFunc, use HandleFunc:
http.Handle("/", i18n.HandleFunc(func(w http.ResponseWriter, r *http.Request) {
rt := i18n.RequestTranslator(r)
fmt.Fprint(w, rt.T("hello"))
}, locales, language.English, i18n.ParseAcceptLanguage))
http.ListenAndServe(":8080", nil)
Functioning
- The i18n handler receives a request.
- It must solve one question: what's the best locale for the user?
- To determine this, it has one or more Parsers (the ones you provided). They have their own way to find a result.
- So the i18n handler questions each parser (in the same order you provided them) and each one gives no, one or more potential locale.
- The i18n handler takes the first locale having a certains confidence threshold, adds a translator to the request context and serves your own handler.
References
- Proposal: Localization support in Go
- Accept-Language used for locale setting — W3C
- Multi-regional and multilingual sites — Google
- Use hreflang for language and regional URLs — Google
- New markup for multilingual content — Google
- Crawling and indexing of locale-adaptive pages — Google
- SEO for multilingual sites: language-specific results without changing URL?
- Geotargeting based on IP address is broken
Documentation
¶
Overview ¶
Package i18n provides internationalization utilities.
Index ¶
- Constants
- func CleanAcceptLanguage(s string) (string, error)
- func ContextWithTranslator(c context.Context, t *Translator) context.Context
- func FmtNumber(l language.Tag, n interface{}) (s string)
- func Handle(h http.Handler, l Locales, fallback language.Tag, parsers ...Parser) http.Handler
- func HandleFunc(f http.HandlerFunc, l Locales, fallback language.Tag, parsers ...Parser) http.Handler
- func ParseAcceptLanguage(r *http.Request) []language.Tag
- func ParseCookie(r *http.Request) []language.Tag
- func ParseFormValue(r *http.Request) []language.Tag
- func RequestWithTranslator(r *http.Request, t *Translator) *http.Request
- func SetCookie(w http.ResponseWriter, r *http.Request)
- type Locales
- type Parser
- type TransFileSize
- type TransFloat64
- type TransInt
- type Translatable
- type Translations
- type Translator
- func (t *Translator) Locale() language.Tag
- func (t *Translator) T(key string, args ...interface{}) string
- func (t *Translator) THTML(key string, args ...interface{}) template.HTML
- func (t *Translator) Tn(key string, n int, args ...interface{}) (s string)
- func (t *Translator) TnHTML(key string, n int, args ...interface{}) template.HTML
Constants ¶
const (
ContextKeyTranslator contextKey = iota
)
Context keys
const LocaleFieldName = "locale"
LocaleFieldName defines the name used for the locale cookie or any parsable field name.
const TnPlaceholder = "{{.n}}"
TnPlaceholder is the placeholder replaced by n in a translation, when using the Tn function.
Variables ¶
This section is empty.
Functions ¶
func CleanAcceptLanguage ¶
CleanAcceptLanguage parses, cleans and returns the contents of a Accept-Language header. If an error is encountered, the returned string is the same as received.
func ContextWithTranslator ¶
func ContextWithTranslator(c context.Context, t *Translator) context.Context
ContextWithTranslator returns the context with the translator t set.
func Handle ¶
Handle returns a handler that will parse the language from the request thanks to the parsers, in the same order they are provided.
func HandleFunc ¶
func HandleFunc(f http.HandlerFunc, l Locales, fallback language.Tag, parsers ...Parser) http.Handler
HandleFunc returns a handler wrapping an http.HandlerFunc and works the same as the Handle function.
func ParseAcceptLanguage ¶
ParseAcceptLanguage parses the Accept-Language header.
func ParseCookie ¶
ParseCookie parses the LocaleFieldName cookie.
func ParseFormValue ¶
ParseFormValue parses the LocaleFieldName form value.
func RequestWithTranslator ¶
func RequestWithTranslator(r *http.Request, t *Translator) *http.Request
RequestWithTranslator returns the HTTP request with the translator t set.
func SetCookie ¶
func SetCookie(w http.ResponseWriter, r *http.Request)
SetCookie writes the response cookie when the parsed request locale differs from the one set inside the LocaleFieldName cookie. If the parsing has not been done yet (request translator is nil), this function can't help you so no cookie will be set.
Types ¶
type Locales ¶
type Locales map[language.Tag]Translations
Locales is a map of locales and their translations.
type Parser ¶
A Parser is a funcion that returns a list of accepted languages according to a request variable (header, URL...), most preferred first.
type TransFileSize ¶
type TransFileSize uint64
TransFileSize is a translatable argument of representing a file size.
type TransFloat64 ¶
type TransFloat64 float64
TransFloat64 is a translatable argument of type float64.
type Translatable ¶
Translatable defines a translatable content that can vary from a language to another.
type Translations ¶
Translations is a map of translations associated to keys.
type Translator ¶
type Translator struct {
// contains filtered or unexported fields
}
A Translator contains the current locale with its translations and provides functions to get them.
func ContextTranslator ¶
func ContextTranslator(c context.Context) *Translator
ContextTranslator returns the translator used for the context.
func RequestTranslator ¶
func RequestTranslator(r *http.Request) *Translator
RequestTranslator returns the translator used for the HTTP request.
func (*Translator) Locale ¶
func (t *Translator) Locale() language.Tag
Locale returns the locale used be the translator.
func (*Translator) T ¶
func (t *Translator) T(key string, args ...interface{}) string
T returns the translation associated to key, for the client locale.
func (*Translator) THTML ¶
func (t *Translator) THTML(key string, args ...interface{}) template.HTML
THTML works like T but returns an HTML unescaped translation. An "nl2br" function is applied to the result.
func (*Translator) Tn ¶
func (t *Translator) Tn(key string, n int, args ...interface{}) (s string)
Tn returns the translation associated to key, for the client locale. If the translation defines plural forms (keys with a "Zero", "One" or "Other" suffix), it uses the most appropriate. All TnPlaceholder in the translation are replaced with number n. When translation is not found, an empty string is returned.
Source Files