doc.go (3577B)
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 message implements formatted I/O for localized strings with functions 6 // analogous to the fmt's print functions. It is a drop-in replacement for fmt. 7 // 8 // # Localized Formatting 9 // 10 // A format string can be localized by replacing any of the print functions of 11 // fmt with an equivalent call to a Printer. 12 // 13 // p := message.NewPrinter(message.MatchLanguage("en")) 14 // p.Println(123456.78) // Prints 123,456.78 15 // 16 // p.Printf("%d ducks in a row", 4331) // Prints 4,331 ducks in a row 17 // 18 // p := message.NewPrinter(message.MatchLanguage("nl")) 19 // p.Printf("Hoogte: %.1f meter", 1244.9) // Prints Hoogte: 1,244.9 meter 20 // 21 // p := message.NewPrinter(message.MatchLanguage("bn")) 22 // p.Println(123456.78) // Prints ১,২৩,৪৫৬.৭৮ 23 // 24 // Printer currently supports numbers and specialized types for which packages 25 // exist in x/text. Other builtin types such as time.Time and slices are 26 // planned. 27 // 28 // Format strings largely have the same meaning as with fmt with the following 29 // notable exceptions: 30 // - flag # always resorts to fmt for printing 31 // - verb 'f', 'e', 'g', 'd' use localized formatting unless the '#' flag is 32 // specified. 33 // - verb 'm' inserts a translation of a string argument. 34 // 35 // See package fmt for more options. 36 // 37 // # Translation 38 // 39 // The format strings that are passed to Printf, Sprintf, Fprintf, or Errorf 40 // are used as keys to look up translations for the specified languages. 41 // More on how these need to be specified below. 42 // 43 // One can use arbitrary keys to distinguish between otherwise ambiguous 44 // strings: 45 // 46 // p := message.NewPrinter(language.English) 47 // p.Printf("archive(noun)") // Prints "archive" 48 // p.Printf("archive(verb)") // Prints "archive" 49 // 50 // p := message.NewPrinter(language.German) 51 // p.Printf("archive(noun)") // Prints "Archiv" 52 // p.Printf("archive(verb)") // Prints "archivieren" 53 // 54 // To retain the fallback functionality, use Key: 55 // 56 // p.Printf(message.Key("archive(noun)", "archive")) 57 // p.Printf(message.Key("archive(verb)", "archive")) 58 // 59 // # Translation Pipeline 60 // 61 // Format strings that contain text need to be translated to support different 62 // locales. The first step is to extract strings that need to be translated. 63 // 64 // 1. Install gotext 65 // 66 // go get -u golang.org/x/text/cmd/gotext 67 // gotext -help 68 // 69 // 2. Mark strings in your source to be translated by using message.Printer, 70 // instead of the functions of the fmt package. 71 // 72 // 3. Extract the strings from your source 73 // 74 // gotext extract 75 // 76 // The output will be written to the textdata directory. 77 // 78 // 4. Send the files for translation 79 // 80 // It is planned to support multiple formats, but for now one will have to 81 // rewrite the JSON output to the desired format. 82 // 83 // 5. Inject translations into program 84 // 85 // 6. Repeat from 2 86 // 87 // Right now this has to be done programmatically with calls to Set or 88 // SetString. These functions as well as the methods defined in 89 // see also package golang.org/x/text/message/catalog can be used to implement 90 // either dynamic or static loading of messages. 91 // 92 // # Plural and Gender Forms 93 // 94 // Translated messages can vary based on the plural and gender forms of 95 // substitution values. In general, it is up to the translators to provide 96 // alternative translations for such forms. See the packages in 97 // golang.org/x/text/feature and golang.org/x/text/message/catalog for more 98 // information. 99 package message