Copyright 2017 The Go Authors. All rights reserved. Use of this source code is governed by a BSD-style license that can be found in the LICENSE file.
Package language implements BCP 47 language tags and related functionality. The most important function of package language is to match a list of user-preferred languages to a list of supported languages. It alleviates the developer of dealing with the complexity of this process and provides the user with the best experience (see https://blog.golang.org/matchlang). Matching preferred against supported languages A Matcher for an application that supports English, Australian English, Danish, and standard Mandarin can be created as follows: var matcher = language.NewMatcher([]language.Tag{ language.English, // The first language is used as fallback. language.MustParse("en-AU"), language.Danish, language.Chinese, }) This list of supported languages is typically implied by the languages for which there exists translations of the user interface. User-preferred languages usually come as a comma-separated list of BCP 47 language tags. The MatchString finds best matches for such strings: handler(w http.ResponseWriter, r *http.Request) { lang, _ := r.Cookie("lang") accept := r.Header.Get("Accept-Language") tag, _ := language.MatchStrings(matcher, lang.String(), accept) // tag should now be used for the initialization of any // locale-specific service. } The Matcher's Match method can be used to match Tags directly. Matchers are aware of the intricacies of equivalence between languages, such as deprecated subtags, legacy tags, macro languages, mutual intelligibility between scripts and languages, and transparently passing BCP 47 user configuration. For instance, it will know that a reader of Bokmål Danish can read Norwegian and will know that Cantonese ("yue") is a good match for "zh-HK". Using match results To guarantee a consistent user experience to the user it is important to use the same language tag for the selection of any locale-specific services. For example, it is utterly confusing to substitute spelled-out numbers or dates in one language in text of another language. More subtly confusing is using the wrong sorting order or casing algorithm for a certain language. All the packages in x/text that provide locale-specific services (e.g. collate, cases) should be initialized with the tag that was obtained at the start of an interaction with the user. Note that Tag that is returned by Match and MatchString may differ from any of the supported languages, as it may contain carried over settings from the user tags. This may be inconvenient when your application has some additional locale-specific data for your supported languages. Match and MatchString both return the index of the matched supported tag to simplify associating such data with the matched tag. Canonicalization If one uses the Matcher to compare languages one does not need to worry about canonicalization. The meaning of a Tag varies per application. The language package therefore delays canonicalization and preserves information as much as possible. The Matcher, however, will always take into account that two different tags may represent the same language. By default, only legacy and deprecated tags are converted into their canonical equivalent. All other information is preserved. This approach makes the confidence scores more accurate and allows matchers to distinguish between variants that are otherwise lost. As a consequence, two tags that should be treated as identical according to BCP 47 or CLDR, like "en-Latn" and "en", will be represented differently. The Matcher handles such distinctions, though, and is aware of the equivalence relations. The CanonType type can be used to alter the canonicalization form. References BCP 47 - Tags for Identifying Languages http://tools.ietf.org/html/bcp47
package language // import "golang.org/x/text/language"
TODO: explanation on how to match languages for your own locale-specific