From 639caa7eb5031c3fc275d5b3bf1f44fe3c3f2623 Mon Sep 17 00:00:00 2001
From: ColinBoisLydia <95220910+ColinBoisLydia@users.noreply.github.com>
Date: Sat, 12 Mar 2022 22:34:15 +0100
Subject: [PATCH] doc(localizer): add specification about language tag
 detection (#270)

---
 v2/i18n/localizer.go | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/v2/i18n/localizer.go b/v2/i18n/localizer.go
index 17261e2e..256cd494 100644
--- a/v2/i18n/localizer.go
+++ b/v2/i18n/localizer.go
@@ -9,6 +9,15 @@ import (
 )
 
 // Localizer provides Localize and MustLocalize methods that return localized messages.
+// Localize and MustLocalize methods use a language.Tag matching algorithm based
+// on the best possible value. This algorithm may cause an unexpected language.Tag returned
+// value depending on the order of the tags stored in memory. For example, if the bundle
+// used to create a Localizer instance ingested locales following this order
+// ["en-US", "en-GB", "en-IE", "en"] and the locale "en" is asked, the underlying matching
+// algorithm will return "en-US" thinking it is the best match possible. More information
+// about the algorithm in this Github issue: https://github.com/golang/go/issues/49176.
+// There is additionnal informations inside the Go code base:
+// https://github.com/golang/text/blob/master/language/match.go#L142
 type Localizer struct {
 	// bundle contains the messages that can be returned by the Localizer.
 	bundle *Bundle