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  // # 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
View as plain text