| // 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 |