1// Copyright 2017 The Go Authors. All rights reserved. 2// Use of this source code is governed by a BSD-style 3// license that can be found in the LICENSE file. 4 5// Package language implements BCP 47 language tags and related functionality. 6// 7// The most important function of package language is to match a list of 8// user-preferred languages to a list of supported languages. 9// It alleviates the developer of dealing with the complexity of this process 10// and provides the user with the best experience 11// (see https://blog.golang.org/matchlang). 12// 13// 14// Matching preferred against supported languages 15// 16// A Matcher for an application that supports English, Australian English, 17// Danish, and standard Mandarin can be created as follows: 18// 19// var matcher = language.NewMatcher([]language.Tag{ 20// language.English, // The first language is used as fallback. 21// language.MustParse("en-AU"), 22// language.Danish, 23// language.Chinese, 24// }) 25// 26// This list of supported languages is typically implied by the languages for 27// which there exists translations of the user interface. 28// 29// User-preferred languages usually come as a comma-separated list of BCP 47 30// language tags. 31// The MatchString finds best matches for such strings: 32// 33// handler(w http.ResponseWriter, r *http.Request) { 34// lang, _ := r.Cookie("lang") 35// accept := r.Header.Get("Accept-Language") 36// tag, _ := language.MatchStrings(matcher, lang.String(), accept) 37// 38// // tag should now be used for the initialization of any 39// // locale-specific service. 40// } 41// 42// The Matcher's Match method can be used to match Tags directly. 43// 44// Matchers are aware of the intricacies of equivalence between languages, such 45// as deprecated subtags, legacy tags, macro languages, mutual 46// intelligibility between scripts and languages, and transparently passing 47// BCP 47 user configuration. 48// For instance, it will know that a reader of Bokmål Danish can read Norwegian 49// and will know that Cantonese ("yue") is a good match for "zh-HK". 50// 51// 52// Using match results 53// 54// To guarantee a consistent user experience to the user it is important to 55// use the same language tag for the selection of any locale-specific services. 56// For example, it is utterly confusing to substitute spelled-out numbers 57// or dates in one language in text of another language. 58// More subtly confusing is using the wrong sorting order or casing 59// algorithm for a certain language. 60// 61// All the packages in x/text that provide locale-specific services 62// (e.g. collate, cases) should be initialized with the tag that was 63// obtained at the start of an interaction with the user. 64// 65// Note that Tag that is returned by Match and MatchString may differ from any 66// of the supported languages, as it may contain carried over settings from 67// the user tags. 68// This may be inconvenient when your application has some additional 69// locale-specific data for your supported languages. 70// Match and MatchString both return the index of the matched supported tag 71// to simplify associating such data with the matched tag. 72// 73// 74// Canonicalization 75// 76// If one uses the Matcher to compare languages one does not need to 77// worry about canonicalization. 78// 79// The meaning of a Tag varies per application. The language package 80// therefore delays canonicalization and preserves information as much 81// as possible. The Matcher, however, will always take into account that 82// two different tags may represent the same language. 83// 84// By default, only legacy and deprecated tags are converted into their 85// canonical equivalent. All other information is preserved. This approach makes 86// the confidence scores more accurate and allows matchers to distinguish 87// between variants that are otherwise lost. 88// 89// As a consequence, two tags that should be treated as identical according to 90// BCP 47 or CLDR, like "en-Latn" and "en", will be represented differently. The 91// Matcher handles such distinctions, though, and is aware of the 92// equivalence relations. The CanonType type can be used to alter the 93// canonicalization form. 94// 95// References 96// 97// BCP 47 - Tags for Identifying Languages http://tools.ietf.org/html/bcp47 98// 99package language // import "golang.org/x/text/language" 100 101// TODO: explanation on how to match languages for your own locale-specific 102// service. 103