github.com/liquid-dev/text@v0.3.3-liquid/message/doc.go (about) 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 // 9 // Localized Formatting 10 // 11 // A format string can be localized by replacing any of the print functions of 12 // fmt with an equivalent call to a Printer. 13 // 14 // p := message.NewPrinter(message.MatchLanguage("en")) 15 // p.Println(123456.78) // Prints 123,456.78 16 // 17 // p.Printf("%d ducks in a row", 4331) // Prints 4,331 ducks in a row 18 // 19 // p := message.NewPrinter(message.MatchLanguage("nl")) 20 // p.Printf("Hoogte: %.1f meter", 1244.9) // Prints Hoogte: 1,244.9 meter 21 // 22 // p := message.NewPrinter(message.MatchLanguage("bn")) 23 // p.Println(123456.78) // Prints ১,২৩,৪৫৬.৭৮ 24 // 25 // Printer currently supports numbers and specialized types for which packages 26 // exist in x/text. Other builtin types such as time.Time and slices are 27 // planned. 28 // 29 // Format strings largely have the same meaning as with fmt with the following 30 // notable exceptions: 31 // - flag # always resorts to fmt for printing 32 // - verb 'f', 'e', 'g', 'd' use localized formatting unless the '#' flag is 33 // specified. 34 // - verb 'm' inserts a translation of a string argument. 35 // 36 // See package fmt for more options. 37 // 38 // 39 // Translation 40 // 41 // The format strings that are passed to Printf, Sprintf, Fprintf, or Errorf 42 // are used as keys to look up translations for the specified languages. 43 // More on how these need to be specified below. 44 // 45 // One can use arbitrary keys to distinguish between otherwise ambiguous 46 // strings: 47 // p := message.NewPrinter(language.English) 48 // p.Printf("archive(noun)") // Prints "archive" 49 // p.Printf("archive(verb)") // Prints "archive" 50 // 51 // p := message.NewPrinter(language.German) 52 // p.Printf("archive(noun)") // Prints "Archiv" 53 // p.Printf("archive(verb)") // Prints "archivieren" 54 // 55 // To retain the fallback functionality, use Key: 56 // p.Printf(message.Key("archive(noun)", "archive")) 57 // p.Printf(message.Key("archive(verb)", "archive")) 58 // 59 // 60 // Translation Pipeline 61 // 62 // Format strings that contain text need to be translated to support different 63 // locales. The first step is to extract strings that need to be translated. 64 // 65 // 1. Install gotext 66 // go get -u github.com/liquid-dev/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 github.com/liquid-dev/text/message/catalog can be used to implement 90 // either dynamic or static loading of messages. 91 // 92 // 93 // Plural and Gender Forms 94 // 95 // Translated messages can vary based on the plural and gender forms of 96 // substitution values. In general, it is up to the translators to provide 97 // alternative translations for such forms. See the packages in 98 // github.com/liquid-dev/text/feature and github.com/liquid-dev/text/message/catalog for more 99 // information. 100 // 101 package message