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