| 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.
|
|---|
