doc.go 4.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102
  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. // Package language implements BCP 47 language tags and related functionality.
  5. //
  6. // The most important function of package language is to match a list of
  7. // user-preferred languages to a list of supported languages.
  8. // It alleviates the developer of dealing with the complexity of this process
  9. // and provides the user with the best experience
  10. // (see https://blog.golang.org/matchlang).
  11. //
  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. //
  51. // Using match results
  52. //
  53. // To guarantee a consistent user experience to the user it is important to
  54. // use the same language tag for the selection of any locale-specific services.
  55. // For example, it is utterly confusing to substitute spelled-out numbers
  56. // or dates in one language in text of another language.
  57. // More subtly confusing is using the wrong sorting order or casing
  58. // algorithm for a certain language.
  59. //
  60. // All the packages in x/text that provide locale-specific services
  61. // (e.g. collate, cases) should be initialized with the tag that was
  62. // obtained at the start of an interaction with the user.
  63. //
  64. // Note that Tag that is returned by Match and MatchString may differ from any
  65. // of the supported languages, as it may contain carried over settings from
  66. // the user tags.
  67. // This may be inconvenient when your application has some additional
  68. // locale-specific data for your supported languages.
  69. // Match and MatchString both return the index of the matched supported tag
  70. // to simplify associating such data with the matched tag.
  71. //
  72. //
  73. // Canonicalization
  74. //
  75. // If one uses the Matcher to compare languages one does not need to
  76. // worry about canonicalization.
  77. //
  78. // The meaning of a Tag varies per application. The language package
  79. // therefore delays canonicalization and preserves information as much
  80. // as possible. The Matcher, however, will always take into account that
  81. // two different tags may represent the same language.
  82. //
  83. // By default, only legacy and deprecated tags are converted into their
  84. // canonical equivalent. All other information is preserved. This approach makes
  85. // the confidence scores more accurate and allows matchers to distinguish
  86. // between variants that are otherwise lost.
  87. //
  88. // As a consequence, two tags that should be treated as identical according to
  89. // BCP 47 or CLDR, like "en-Latn" and "en", will be represented differently. The
  90. // Matcher handles such distinctions, though, and is aware of the
  91. // equivalence relations. The CanonType type can be used to alter the
  92. // canonicalization form.
  93. //
  94. // References
  95. //
  96. // BCP 47 - Tags for Identifying Languages http://tools.ietf.org/html/bcp47
  97. //
  98. package language // import "golang.org/x/text/language"
  99. // TODO: explanation on how to match languages for your own locale-specific
  100. // service.