100 lines
3.5 KiB
Go
100 lines
3.5 KiB
Go
// 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 message implements formatted I/O for localized strings with functions
|
|
// analogous to the fmt's print functions. It is a drop-in replacement for fmt.
|
|
//
|
|
// # Localized Formatting
|
|
//
|
|
// A format string can be localized by replacing any of the print functions of
|
|
// fmt with an equivalent call to a Printer.
|
|
//
|
|
// p := message.NewPrinter(message.MatchLanguage("en"))
|
|
// p.Println(123456.78) // Prints 123,456.78
|
|
//
|
|
// p.Printf("%d ducks in a row", 4331) // Prints 4,331 ducks in a row
|
|
//
|
|
// p := message.NewPrinter(message.MatchLanguage("nl"))
|
|
// p.Printf("Hoogte: %.1f meter", 1244.9) // Prints Hoogte: 1,244.9 meter
|
|
//
|
|
// p := message.NewPrinter(message.MatchLanguage("bn"))
|
|
// p.Println(123456.78) // Prints ১,২৩,৪৫৬.৭৮
|
|
//
|
|
// Printer currently supports numbers and specialized types for which packages
|
|
// exist in x/text. Other builtin types such as time.Time and slices are
|
|
// planned.
|
|
//
|
|
// Format strings largely have the same meaning as with fmt with the following
|
|
// notable exceptions:
|
|
// - flag # always resorts to fmt for printing
|
|
// - verb 'f', 'e', 'g', 'd' use localized formatting unless the '#' flag is
|
|
// specified.
|
|
// - verb 'm' inserts a translation of a string argument.
|
|
//
|
|
// See package fmt for more options.
|
|
//
|
|
// # Translation
|
|
//
|
|
// The format strings that are passed to Printf, Sprintf, Fprintf, or Errorf
|
|
// are used as keys to look up translations for the specified languages.
|
|
// More on how these need to be specified below.
|
|
//
|
|
// One can use arbitrary keys to distinguish between otherwise ambiguous
|
|
// strings:
|
|
//
|
|
// p := message.NewPrinter(language.English)
|
|
// p.Printf("archive(noun)") // Prints "archive"
|
|
// p.Printf("archive(verb)") // Prints "archive"
|
|
//
|
|
// p := message.NewPrinter(language.German)
|
|
// p.Printf("archive(noun)") // Prints "Archiv"
|
|
// p.Printf("archive(verb)") // Prints "archivieren"
|
|
//
|
|
// To retain the fallback functionality, use Key:
|
|
//
|
|
// p.Printf(message.Key("archive(noun)", "archive"))
|
|
// p.Printf(message.Key("archive(verb)", "archive"))
|
|
//
|
|
// # Translation Pipeline
|
|
//
|
|
// Format strings that contain text need to be translated to support different
|
|
// locales. The first step is to extract strings that need to be translated.
|
|
//
|
|
// 1. Install gotext
|
|
//
|
|
// go get -u golang.org/x/text/cmd/gotext
|
|
// gotext -help
|
|
//
|
|
// 2. Mark strings in your source to be translated by using message.Printer,
|
|
// instead of the functions of the fmt package.
|
|
//
|
|
// 3. Extract the strings from your source
|
|
//
|
|
// gotext extract
|
|
//
|
|
// The output will be written to the textdata directory.
|
|
//
|
|
// 4. Send the files for translation
|
|
//
|
|
// It is planned to support multiple formats, but for now one will have to
|
|
// rewrite the JSON output to the desired format.
|
|
//
|
|
// 5. Inject translations into program
|
|
//
|
|
// 6. Repeat from 2
|
|
//
|
|
// Right now this has to be done programmatically with calls to Set or
|
|
// SetString. These functions as well as the methods defined in
|
|
// see also package golang.org/x/text/message/catalog can be used to implement
|
|
// either dynamic or static loading of messages.
|
|
//
|
|
// # Plural and Gender Forms
|
|
//
|
|
// Translated messages can vary based on the plural and gender forms of
|
|
// substitution values. In general, it is up to the translators to provide
|
|
// alternative translations for such forms. See the packages in
|
|
// golang.org/x/text/feature and golang.org/x/text/message/catalog for more
|
|
// information.
|
|
package message
|