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 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// 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// golang.org/x/text/feature and golang.org/x/text/message/catalog for more 99// information. 100// 101package message 102