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

100