Package message

Overview ▾

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(message.MatchLanguage("en"))
p.Println(123456.78) // Prints 123,456.78

p.Printf("%d ducks in a row", 4331) // Prints 4,331 ducks in a row

p := message.NewPrinter(message.MatchLanguage("nl"))
p.Printf("Hoogte: %.1f meter", 1244.9) // Prints Hoogte: 1,244.9 meter

p := message.NewPrinter(message.MatchLanguage("bn"))
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.
• verb 'm' inserts a translation of a string argument.

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.

// languages supported by this service:
http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
    lang, _ := r.Cookie("lang")
    accept := r.Header.Get("Accept-Language")
    fallback := "en"
    tag := message.MatchLanguage(lang.String(), accept, fallback)

    p := message.NewPrinter(tag)

    p.Fprintln(w, "User language is", tag)
})

Index ▾

Package files

catalog.go doc.go format.go message.go print.go