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 (
