message: add documentation and examples Change-Id: I5b96c78428b1650d13f56db02a7afed295c7298e Reviewed-on: https://go-review.googlesource.com/59030 Run-TryBot: Marcel van Lohuizen <mpvl@golang.org> TryBot-Result: Gobot Gobot <gobot@golang.org> Reviewed-by: Nigel Tao <nigeltao@golang.org>
diff --git a/message/doc.go b/message/doc.go new file mode 100644 index 0000000..60424a6 --- /dev/null +++ b/message/doc.go
@@ -0,0 +1,95 @@ +// 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(language.English) +// p.Println(123456.78) // Prints 123,456.78 +// +// p := message.NewPrinter(language.Bengali) +// 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. +// +// 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
diff --git a/message/examples_test.go b/message/examples_test.go new file mode 100644 index 0000000..c73eaf9 --- /dev/null +++ b/message/examples_test.go
@@ -0,0 +1,42 @@ +// 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_test + +import ( + "net/http" + + "golang.org/x/text/language" + "golang.org/x/text/message" +) + +func Example_http() { + // languages supported by this service: + matcher := language.NewMatcher(message.DefaultCatalog.Languages()) + + http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) { + lang, _ := r.Cookie("lang") + accept := r.Header.Get("Accept-Language") + fallback := "en" + tag, _ := language.MatchStrings(matcher, lang.String(), accept, fallback) + + p := message.NewPrinter(tag) + + p.Fprintln(w, "User language is", tag) + }) +} + +func ExamplePrinter_numbers() { + for _, lang := range []string{"en", "de", "de-CH", "fr", "bn"} { + p := message.NewPrinter(language.Make(lang)) + p.Printf("%-6s %g\n", lang, 123456.78) + } + + // Output: + // en 123,456.78 + // de 123.456,78 + // de-CH 123’456.78 + // fr 123 456,78 + // bn ১,২৩,৪৫৬.৭৮ +}
diff --git a/message/message.go b/message/message.go index 187b26f..ba4f95a 100644 --- a/message/message.go +++ b/message/message.go
@@ -2,15 +2,6 @@ // 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. -// -// These are the important differences with fmt: -// - Output varies per locale. -// - The '#' flag is used to bypass localization. -// -// NOTE: Under construction. See https://golang.org/design/12750-localization -// and its corresponding proposal issue https://golang.org/issues/12750. package message // import "golang.org/x/text/message" import (