i18n

README

Package i18n is a handler and helper for the core.
It provides internationalization functions following the client preferences.

Documentation

Overview

Package i18n is a handler and helper for the core (https://godoc.org/github.com/volatile/core). It provides internationalization functions following the client preferences.

Set translations

A translation is associated to a key, which is associated to a language tag, which is part of Locales map.

All translations can be stored like this:

var locales = i18n.Locales{
	language.English: {
		"decimalMark":   ".",
		"thousandsMark": ",",

		"hello":         "Hello %s,",
		"how":           "How are you?",
		"basementZero":  "All the money hidden in your basement has been spent.",
		"basementOne":   "A single dollar remains in your basement.",
		"basementOther": "You have " + i18n.TnPlaceholder + " bucks in your basement.",
	},
	language.French: {
		"decimalMark":   ",",
		"thousandsMark": " ",

		"hello":         "Bonjour %s,",
		"how":           "Comment allez-vous?",
		"basementZero":  "Tout l'argent caché dans votre sous-sol a été dépensé.",
		"basementOne":   "Un seul dollar se trouve dans votre sous-sol.",
		"basementOther": "Vous avez " + i18n.TnPlaceholder + " briques dans votre sous-sol.",
	},
}

decimalMark and thousandsMark are special keys that define the digits separators for decimals and thousands when using Tn or Fmtn.

With these translations, you need to Init this package (the second argument is the default locale):

i18n.Init(locales, language.English)

Detect client locale

When a client makes a request, the best locale must be matched to his preferences. To achieve this, you need to Use the handler with one or more matchers:

i18n.Use(i18n.MatcherFormValue, i18n.MatcherAcceptLanguageHeader)

The client locale is set as soon as a matcher is confident.

A matcher is a function that returns the locale parsed from core.Context with its level of confidence. These ones are actually available: MatcherAcceptLanguageHeader and MatcherFormValue.

Use translations

A translation can be accessed with T, receiving the core.Context (which contains the matched locale), the translation key, and optional arguments (if the translation contains formatting verbs):

i18n.T(c, "hello", "Walter White")
i18n.T(c, "how")

If a translation has pluralized forms, you can use Tn and the most appropriate form will be used according to the quantity:

i18n.Tn(c, "basement", 333000.333)

will result in "You have 333,000.333 bucks in your basement.".

If you use templates, TemplatesFuncs provides a map of all usable functions. Example with package response (https://godoc.org/github.com/volatile/response) package:

response.TemplatesFuncs(i18n.TemplatesFuncs)

Index

• Constants
• Variables
• func CleanAcceptLanguage(s string) (string, error)
• func ClientLocale(c *core.Context) language.Tag
• func Fmtn(c *core.Context, n interface{}) (s string)
• func HT(c *core.Context, key string, a ...interface{}) template.HTML
• func HTn(c *core.Context, key string, n interface{}, a ...interface{}) template.HTML
• func Init(ll Locales, def language.Tag)
• func Match(tt ...language.Tag) (t language.Tag, c language.Confidence)
• func MatchString(s string) (language.Tag, language.Confidence)
• func MatcherAcceptLanguageHeader(c *core.Context) (language.Tag, language.Confidence)
• func MatcherFormValue(c *core.Context) (language.Tag, language.Confidence)
• func SetClientLocale(c *core.Context, t language.Tag) error
• func T(c *core.Context, key string, a ...interface{}) string
• func Tn(c *core.Context, key string, n interface{}, a ...interface{}) (s string)
• func Use(matchers ...Matcher)
• type Locales
  • func (ll *Locales) Has(t language.Tag) bool
• type Matcher
• type Translations

Constants

const TnPlaceholder = "{{.n}}"

TnPlaceholder is the placeholder replaced by n in a translation, when using the TransN function.

Variables

var (
	ErrUnknownLocale = errors.New("i18n: unknown locale")
)

Errors

var TemplatesFuncs = map[string]interface{}{
	"clientLocale": ClientLocale,
	"fmtn":         Fmtn,
	"t":            T,
	"ht":           HT,
	"tn":           Tn,
	"htn":          HTn,
}

TemplatesFuncs provides i18n functions that can be set for templates.

Functions

func CleanAcceptLanguage

func CleanAcceptLanguage(s string) (string, error)

CleanAcceptLanguage parses, cleans and returns the contents of a Accept-Language header. If an error is encountered, the returned string is the same as given.

func ClientLocale

func ClientLocale(c *core.Context) language.Tag

ClientLocale returns the current locale used for the client.

func Fmtn

func Fmtn(c *core.Context, n interface{}) (s string)

Fmtn returns a formatted number with decimal and thousands marks, according to the locale's "decimalMark" and "thousandsMark" keys respectively. If not set, the decimal mark is "," and the thousands mark is ".".

func HT

func HT(c *core.Context, key string, a ...interface{}) template.HTML

HT works like T but returns an HTML unescaped translation.

func HTn

func HTn(c *core.Context, key string, n interface{}, a ...interface{}) template.HTML

HTn works like Tn but returns an HTML unescaped translation.

func Init

func Init(ll Locales, def language.Tag)

Init registers locales ll and default locale def for the entire app.

func Match

func Match(tt ...language.Tag) (t language.Tag, c language.Confidence)

Match matches the first of the given tags to reach a certain confidence threshold with an available locale. The tags should therefore be specified in order of preference. Extensions are ignored for matching.

func MatchString

func MatchString(s string) (language.Tag, language.Confidence)

MatchString parses string s and matches the first of the given tags to reach a certain confidence threshold with an available locale. The string can be a single language tag or a list of language tags with preference values (from the Accept-Language header, for example).

func MatcherAcceptLanguageHeader

func MatcherAcceptLanguageHeader(c *core.Context) (language.Tag, language.Confidence)

MatcherAcceptLanguageHeader matches the Accept-Language header.

func MatcherFormValue

func MatcherFormValue(c *core.Context) (language.Tag, language.Confidence)

MatcherFormValue matches the "locale" form value.

func SetClientLocale

func SetClientLocale(c *core.Context, t language.Tag) error

SetClientLocale sets the locale used for the client. If the locale described by language tag t doesn't exist, error ErrUnknownLocale is returned.

func T

func T(c *core.Context, key string, a ...interface{}) string

T returns the translation associated to key, for the client locale.

func Tn

func Tn(c *core.Context, key string, n interface{}, a ...interface{}) (s string)

Tn returns the translation associated to key, for the client locale. If the translation defines plural forms (zero, one, other), it uses the most apropriate. All TnPlaceholder in the translation are replaced with number n.

func Use

func Use(matchers ...Matcher)

Use adds the handler to the default handlers stack. It matches locale for client, thanks to matchers. Multiple matchers can be used. The client locale is set as soon as a matcher is confident.

Types

type Locales

type Locales map[language.Tag]Translations

Locales is a map of translations associated to language tags.

func (*Locales) Has

func (ll *Locales) Has(t language.Tag) bool

Has checks if locale t exists in the locales map.

type Matcher

type Matcher func(*core.Context) (language.Tag, language.Confidence)

Matcher is a matching function used by the handler.

type Translations

type Translations map[string]string

Translations is a map of translations.