x/text/message: package level docs about MatchLanguage are unclear

[svip]

Please answer these questions before submitting your issue. Thanks!

What version of Go are you using (go version)?

go1.11 linux/amd64

Does this issue reproduce with the latest release?

Yes.

What operating system and processor architecture are you using (go env)?

linux/amd64

What did you do?

I tried to use message.MatchLanguage("nl") to obtain language.Dutch, as per the example on its site.

See the following code for an example:

package main

import (
	"golang.org/x/text/message"
	"golang.org/x/text/language"
	"fmt"
)

func main() {
	nl := message.MatchLanguage("nl")
	fmt.Println(nl) // Prints "und", expected "nl"
	fmt.Println(language.Dutch) // Prints "nl" as expected
	p := message.NewPrinter(message.MatchLanguage("nl"))
	p.Printf("%.2f\n", 5000.00) // Prints "5,000.00", expected "5.000,00"

	p2 := message.NewPrinter(message.MatchLanguage("bn"))
	p2.Println(123456.78) // Prints "5,000.00", expected "১,২৩,৪৫৬.৭৮"
}

What did you expect to see?

I expected to receive language.Dutch, so that when I called p.Printf("%.2f\n", 5000.00), I would get "5.000,00", as Dutch uses "." for thousand separators and "," for decimal separators.

What did you see instead?

Instead message.MatchLanguage("nl") returned the und Tag rather than the Dutch Tag. And therefore when I called p.Printf() as per the example on the package's description, I got "5,000.00", which ironically matches the example in the description, but the example is wrong.

I also tried the third example in opening example, which also did not seem to produce the expected result.

It seems to me that message.MatchLanguage() either does not work or does not work as described.

Note: Making a new Printer with language.Dutch works as expected.

[ianlancetaylor]

CC @mpvl

[SamWhited]

If I understand your example correctly, you are attempting to match using the language matcher from the default catalog. However, you haven't added any strings (and thus no languages) to the catalog. Something like this works, so I think this is expected behavior (and just an unclear example in the docs):

package main

import (
	"fmt"
	"golang.org/x/text/language"
	"golang.org/x/text/message"
	"golang.org/x/text/message/catalog"
)

func main() {
	fmt.Println("No strings:")
	nl := message.MatchLanguage("nl")
	fmt.Println(nl) // Prints "und"
	p := message.NewPrinter(nl)
	p.Printf("%.2f\n", 5000.00) // Prints "5,000.00"

	fmt.Println("With Dutch string:")
	message.Set(language.Dutch, "Hoogte", catalog.String("Hoogte"))
	nl = message.MatchLanguage("nl")
	fmt.Println(nl) // Prints "nl"
	p = message.NewPrinter(nl)
	p.Printf("%.2f\n", 5000.00) // Prints "5.000,00"
}

I have relabeled this as a documentation issue (unless of course @mpvl says otherwise).

[svip]

Ah, OK, that makes sense. It's just not very well explained in the documentation, hence I got the wrong impression. But that means basically what I want to do in my scenario is call NewPrinter() with NewPrinter(language.Dutch), because I know the language beforehand.

[SamWhited]

@svip see also this CL https://golang.org/cl/127598 in which this was brought up which I just remembered. I'm trying to think of a better way to clarify this in the docs than using a language tag directly (which, as Marcel points out, is probably rare).