Documentation
¶
Overview ¶
Package locale provides middleware that picks the response language from the request and hands it to validate to translate validation messages.
The locale comes from, in order, an optional query parameter, an optional cookie, and the Accept-Language header with its q-values. Each candidate is matched against the locales of the catalog, first exactly and then by base language ("es" for "es-MX"). Without a match the catalog default is used.
Catalog tags have ASCII language-tag shape. Case, surrounding whitespace, and underscores are normalized for matching; context keeps the original catalog key, while Content-Language trims whitespace and replaces underscores with hyphens. Invalid tags, ambiguous normalized keys, or invalid nonempty cookie names panic after all callbacks. An empty catalog falls back to English, and empty query/cookie names disable those selectors. The middleware only reads cookies; it does not issue cookies or configure their lifetime.
HTTP quality values must be zero or one with at most three decimal digits; only zeros may follow one. Malformed, nonfinite, duplicate, or q=0 preferences are ignored. Tag checks cover the basic ASCII shape, not the full BCP 47 grammar or a registry lookup.
Example:
routes := router.New()
routes.Use(locale.Middleware(func(language *locale.Builder) {
language.QueryParam("lang")
language.Cookie("language")
}))
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FromContext ¶
FromContext returns the locale stored by Middleware, or an empty string when the context has none. It preserves the catalog key for translation lookup; Content-Language instead trims whitespace and replaces underscores with "-".
Example:
tag := locale.FromContext(request.Context()) fmt.Println(tag)
func Middleware ¶
func Middleware(configure ...BuilderFunc) router.Middleware
Middleware returns middleware that resolves the request locale and stores it, with the catalog, in the request context for validate.
It sets Content-Language to the resolved locale and adds Accept-Language (and Cookie, when a cookie is configured) to Vary. The headers are also attached to the problem response context, so error responses carry them.
Retrieve the locale downstream with FromContext. Invalid catalog tags, ambiguous normalized keys, and invalid nonempty cookie names panic after all callbacks. The empty catalog and empty selector names retain their fallback/disabled meanings. Malformed HTTP quality values, including nonfinite numbers or duplicate q parameters, are ignored.
Example:
routes.Use(locale.Middleware(func(language *locale.Builder) {
language.QueryParam("lang")
language.Cookie("language")
}))
Types ¶
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder configures Middleware before publication. Callbacks run directly once, synchronously in order on one fresh draft; nil entries panic. Retaining the draft cannot change published settings. Methods return the same draft.
Example:
r := router.New()
r.Use(locale.Middleware(func(language *locale.Builder) {
language.QueryParam("lang")
}))
func (*Builder) Catalog ¶
Catalog holds the supported locales, which are its Locales keys, and the default locale. Middleware uses the built-in English messages. An empty Default falls back to "en"; an empty catalog remains valid. Keys and a nonempty Default must have language-tag shape: one to eight ASCII letters, followed by optional one-to-eight-character alphanumeric subtags. Matching ignores case, surrounding whitespace, and the distinction between "_" and "-". Two keys with the same normalized spelling are ambiguous and panic at publication, as do invalid tags. Message maps remain detached from the caller.
The setting replaces the previous value on this construction draft. Publication keeps independent settings; functions and services stay shared.
Example:
r := router.New()
catalog := validate.Catalog{
Default: "en",
Locales: map[string]validate.Messages{"en": validate.English()},
}
r.Use(locale.Middleware(func(language *locale.Builder) {
language.Catalog(catalog)
}))
func (*Builder) Cookie ¶
Cookie names a cookie that selects the locale when the query parameter is absent or unsupported. Empty disables it. A nonempty name must pass net/http.Cookie.Valid; Middleware panics for an invalid final name after running every construction callback. This middleware never writes cookies and has no cookie lifetime or duration setting.
The setting replaces the previous value on this construction draft. Publication keeps independent settings; functions and services stay shared.
Example:
r := router.New()
r.Use(locale.Middleware(func(language *locale.Builder) {
language.Cookie("language")
}))
func (*Builder) QueryParam ¶
QueryParam names a query parameter that selects the locale and wins over every other source. Empty disables it.
The setting replaces the previous value on this construction draft. Publication keeps independent settings; functions and services stay shared.
Example:
r := router.New()
r.Use(locale.Middleware(func(language *locale.Builder) {
language.QueryParam("lang")
}))
type BuilderFunc ¶
type BuilderFunc = func(*Builder)
BuilderFunc edits one locale construction draft. Policies run once, synchronously in order, before final tag and cookie-name validation. A supplied nil policy panics; an expanded nil slice supplies no policies. Catalog maps are detached at publication, including maps kept through a retained draft.
Example:
var selectLanguage locale.BuilderFunc = func(language *locale.Builder) {
language.QueryParam("lang")
}
routes.Use(locale.Middleware(selectLanguage))
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
negotiation
Package negotiation resolves original catalog keys from HTTP preferences.
|
Package negotiation resolves original catalog keys from HTTP preferences. |