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.