vendor/golang.org/x/text/language/doc.go

   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 //
  99 package language // import "golang.org/x/text/language"
 100
 101 // TODO: explanation on how to match languages for your own locale-specific
 102 // service.