You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
102 lines
4.3 KiB
102 lines
4.3 KiB
// Copyright 2017 The Go Authors. All rights reserved. |
|
// Use of this source code is governed by a BSD-style |
|
// license that can be found in the LICENSE file. |
|
|
|
// Package language implements BCP 47 language tags and related functionality. |
|
// |
|
// The most important function of package language is to match a list of |
|
// user-preferred languages to a list of supported languages. |
|
// It alleviates the developer of dealing with the complexity of this process |
|
// and provides the user with the best experience |
|
// (see https://blog.golang.org/matchlang). |
|
// |
|
// |
|
// Matching preferred against supported languages |
|
// |
|
// A Matcher for an application that supports English, Australian English, |
|
// Danish, and standard Mandarin can be created as follows: |
|
// |
|
// var matcher = language.NewMatcher([]language.Tag{ |
|
// language.English, // The first language is used as fallback. |
|
// language.MustParse("en-AU"), |
|
// language.Danish, |
|
// language.Chinese, |
|
// }) |
|
// |
|
// This list of supported languages is typically implied by the languages for |
|
// which there exists translations of the user interface. |
|
// |
|
// User-preferred languages usually come as a comma-separated list of BCP 47 |
|
// language tags. |
|
// The MatchString finds best matches for such strings: |
|
// |
|
// handler(w http.ResponseWriter, r *http.Request) { |
|
// lang, _ := r.Cookie("lang") |
|
// accept := r.Header.Get("Accept-Language") |
|
// tag, _ := language.MatchStrings(matcher, lang.String(), accept) |
|
// |
|
// // tag should now be used for the initialization of any |
|
// // locale-specific service. |
|
// } |
|
// |
|
// The Matcher's Match method can be used to match Tags directly. |
|
// |
|
// Matchers are aware of the intricacies of equivalence between languages, such |
|
// as deprecated subtags, legacy tags, macro languages, mutual |
|
// intelligibility between scripts and languages, and transparently passing |
|
// BCP 47 user configuration. |
|
// For instance, it will know that a reader of Bokmål Danish can read Norwegian |
|
// and will know that Cantonese ("yue") is a good match for "zh-HK". |
|
// |
|
// |
|
// Using match results |
|
// |
|
// To guarantee a consistent user experience to the user it is important to |
|
// use the same language tag for the selection of any locale-specific services. |
|
// For example, it is utterly confusing to substitute spelled-out numbers |
|
// or dates in one language in text of another language. |
|
// More subtly confusing is using the wrong sorting order or casing |
|
// algorithm for a certain language. |
|
// |
|
// All the packages in x/text that provide locale-specific services |
|
// (e.g. collate, cases) should be initialized with the tag that was |
|
// obtained at the start of an interaction with the user. |
|
// |
|
// Note that Tag that is returned by Match and MatchString may differ from any |
|
// of the supported languages, as it may contain carried over settings from |
|
// the user tags. |
|
// This may be inconvenient when your application has some additional |
|
// locale-specific data for your supported languages. |
|
// Match and MatchString both return the index of the matched supported tag |
|
// to simplify associating such data with the matched tag. |
|
// |
|
// |
|
// Canonicalization |
|
// |
|
// If one uses the Matcher to compare languages one does not need to |
|
// worry about canonicalization. |
|
// |
|
// The meaning of a Tag varies per application. The language package |
|
// therefore delays canonicalization and preserves information as much |
|
// as possible. The Matcher, however, will always take into account that |
|
// two different tags may represent the same language. |
|
// |
|
// By default, only legacy and deprecated tags are converted into their |
|
// canonical equivalent. All other information is preserved. This approach makes |
|
// the confidence scores more accurate and allows matchers to distinguish |
|
// between variants that are otherwise lost. |
|
// |
|
// As a consequence, two tags that should be treated as identical according to |
|
// BCP 47 or CLDR, like "en-Latn" and "en", will be represented differently. The |
|
// Matcher handles such distinctions, though, and is aware of the |
|
// equivalence relations. The CanonType type can be used to alter the |
|
// canonicalization form. |
|
// |
|
// References |
|
// |
|
// BCP 47 - Tags for Identifying Languages http://tools.ietf.org/html/bcp47 |
|
// |
|
package language // import "golang.org/x/text/language" |
|
|
|
// TODO: explanation on how to match languages for your own locale-specific |
|
// service.
|
|
|