feat: support inline multi-form plurals and refined language rules

- Added support for inline multi-form plural syntax: {{plural:count|one:item|other:{{count}} items}}
- Refined plural rules for French (0 and 1 are 'one')
- Added more comprehensive language coverage in internal/plural
- Updated README, docs, tests, and examples with new pluralization features

Author: cmelgarejo

README.md

@@ -52,6 +52,8 @@ set:
   items.count:
     short: You have {{count}} {{plural:count|item|items}}
     long: Total: {{num:amount}} generated at {{date:when}}
+  person.cats:
+    short: "{{plural:count|zero:No cats|one:One cat|other:{{count}} cats}}"
 ```
 
 Example `es.yaml`:
@@ -146,6 +148,7 @@ All fields of `msgcat.Config`:
 - **Template tokens (named parameters)**
   - `{{name}}` — simple substitution.
   - `{{plural:count|singular|plural}}` — binary plural by named count parameter.
+  - `{{plural:count|one:item|few:items|many:items|other:items}}` — multi-form plural by named count parameter using CLDR rules (supports 0, 1, 2, few, many, other depending on language).
   - **CLDR plural forms** — optional `short_forms` / `long_forms` per entry (keys: `zero`, `one`, `two`, `few`, `many`, `other`) for full locale rules; see [CLDR and messages in Go](docs/CLDR_AND_GO_MESSAGES_PLAN.md).
   - `{{num:amount}}` — localized number for named parameter.
   - `{{date:when}}` — localized date for named parameter (`time.Time` or `*time.Time`).

docs/CLDR_AND_GO_MESSAGES_PLAN.md

@@ -2,19 +2,20 @@
 
 Plan to add **CLDR-style plural forms** and **messages defined in Go with extract** to msgcat, closing the gap with go-i18n.
 
-**Implementation status:** Done. Library has `ShortForms`/`LongForms`/`PluralParam` on `RawMessage`, `internal/plural` for form selection, `MessageDef` type, CLI extract finds MessageDef literals and merges into YAML, merge copies plural fields. See README, examples/cldr_plural, examples/msgdef.
+**Implementation status:** Done. Library has `ShortForms`/`LongForms`/`PluralParam` on `RawMessage`, **inline multi-form plural syntax** `{{plural:count|one:...|other:...}}`, `internal/plural` for form selection, `MessageDef` type, CLI extract finds MessageDef literals and merges into YAML, merge copies plural fields. See README, examples/cldr_plural, examples/msgdef.
 
 ---
 
 ## 1. CLDR plurals
 
 ### 1.1 Goal
 
-Support the full set of CLDR plural categories (**zero**, **one**, **two**, **few**, **many**, **other**) so that languages with more than two forms (e.g. Arabic, Russian, Welsh) can have correct pluralization. Current msgcat only has binary `{{plural:count|singular|plural}}`.
+Support the full set of CLDR plural categories (**zero**, **one**, **two**, **few**, **many**, **other**) so that languages with more than two forms (e.g. Arabic, Russian, Welsh) can have correct pluralization. Support both optional entry-level maps and **inline multi-form tokens**.
 
 ### 1.2 Backward compatibility
 
-- Keep existing **short** / **long** strings and **`{{plural:count|singular|plural}}`** unchanged. No breaking change.
+- Keep existing **short** / **long** strings and **`{{plural:count|singular|plural}}`** (binary) unchanged. No breaking change.
+- Add **inline multi-form support**: `{{plural:count|one:item|other:items}}` uses the language rule to pick a form.
 - Add **optional** plural form maps. When present, they are used instead of the binary plural token for that entry.
 
 ### 1.3 YAML format (optional plural forms)
@@ -162,7 +163,7 @@ type MessageDef struct {
 
 ## 4. Out of scope (for this plan)
 
-- **Changing existing binary plural token:** `{{plural:count|singular|plural}}` stays as-is when CLDR forms are not used.
+- **Changing existing binary plural token:** `{{plural:count|singular|plural}}` stays as-is (backward compatible). Added **multi-form plural token** `{{plural:count|one:singular|other:plural|few:...}}` for inline CLDR rules.
 - **Runtime default message from Go:** Passing a MessageDef into GetMessageWithCtx as fallback when key is missing is a possible later extension.
 - **Hash/change detection** for merged translations (like goi18n) remains out of scope.
 

examples/cldr_plural/main.go

@@ -31,6 +31,8 @@ set:
       one: "{{name}} has one cat."
       other: "{{name}} has {{count}} cats."
     plural_param: count
+  person.dogs:
+    short: "{{name}} has {{plural:count|zero:no dogs|one:one dog|other:{{count}} dogs}}"
 `)
 	if err := os.WriteFile(filepath.Join(dir, "en.yaml"), en, 0o600); err != nil {
 		panic(err)
@@ -45,6 +47,26 @@ set:
 
 	for _, count := range []int{0, 1, 2, 5} {
 		msg := catalog.GetMessageWithCtx(ctx, "person.cats", msgcat.Params{"name": "Nick", "count": count})
-		fmt.Printf("count=%d: %s\n", count, msg.ShortText)
+		fmt.Printf("cats count=%d: %s\n", count, msg.ShortText)
+		msgDog := catalog.GetMessageWithCtx(ctx, "person.dogs", msgcat.Params{"name": "Nick", "count": count})
+		fmt.Printf("dogs count=%d: %s\n", count, msgDog.ShortText)
+	}
+
+	ar := []byte(`default:
+  short: خطأ
+  long: خطأ
+set:
+  person.dogs:
+    short: "{{name}} لديه {{plural:count|zero:لا كلاب|one:كلب واحد|two:كلبان|few:{{count}} كلاب|many:{{count}} كلباً|other:{{count}} كلب}}"
+`)
+	if err := os.WriteFile(filepath.Join(dir, "ar.yaml"), ar, 0o600); err != nil {
+		panic(err)
+	}
+	msgcat.Reload(catalog)
+
+	ctxAR := context.WithValue(context.Background(), "language", "ar")
+	for _, count := range []int{0, 1, 2, 5, 11, 100} {
+		msgDog := catalog.GetMessageWithCtx(ctxAR, "person.dogs", msgcat.Params{"name": "Nick", "count": count})
+		fmt.Printf("AR dogs count=%d: %s\n", count, msgDog.ShortText)
 	}
 }

internal/plural/plural.go

@@ -25,11 +25,13 @@ func Form(lang string, count int) string {
 		return formRussian(n)
 	case "pl":
 		return formPolish(n)
+	case "fr", "pt", "oc", "it":
+		return formFrench(n)
 	case "cy", "br", "ga", "gd", "gv", "kw", "mt", "sm", "ak":
 		return formWelsh(n)
 	case "he", "iw":
 		return formHebrew(n)
-	case "en", "es", "fr", "de", "it", "pt", "nl", "no", "sv", "da", "fi", "tr", "el", "ja", "ko", "zh", "th", "vi", "id", "hi":
+	case "en", "es", "de", "nl", "no", "sv", "da", "fi", "tr", "el", "ja", "ko", "zh", "th", "vi", "id", "hi":
 		return formOneOther(n)
 	default:
 		return "other"
@@ -43,6 +45,13 @@ func formOneOther(n int) string {
 	return "other"
 }
 
+func formFrench(n int) string {
+	if n == 0 || n == 1 {
+		return "one"
+	}
+	return "other"
+}
+
 func formArabic(n int) string {
 	if n == 0 {
 		return "zero"

internal/plural/plural_test.go

@@ -14,6 +14,9 @@ func TestForm(t *testing.T) {
 		{"en-US", 1, "one"},
 		{"es", 1, "one"},
 		{"es", 5, "other"},
+		{"fr", 0, "one"},
+		{"fr", 1, "one"},
+		{"fr", 2, "other"},
 		{"ar", 0, "zero"},
 		{"ar", 1, "one"},
 		{"ar", 2, "two"},

msgcat.go

@@ -31,7 +31,7 @@ var messageKeyRegex = regexp.MustCompile(`^[a-zA-Z0-9_.-]+$`)
 
 var (
 	simplePlaceholderRegex = regexp.MustCompile(`\{\{([a-zA-Z_][a-zA-Z0-9_.]*)\}\}`)
-	pluralPlaceholderRegex = regexp.MustCompile(`\{\{plural:([a-zA-Z_][a-zA-Z0-9_.]*)\|([^|}]*)\|([^}]*)\}\}`)
+	pluralPlaceholderRegex = regexp.MustCompile(`\{\{plural:([a-zA-Z_][a-zA-Z0-9_.]*)\|((?:[^{}]|\{\{.*?\}\})*)\}\}`)
 	numberPlaceholderRegex = regexp.MustCompile(`\{\{num:([a-zA-Z_][a-zA-Z0-9_.]*)\}\}`)
 	datePlaceholderRegex   = regexp.MustCompile(`\{\{date:([a-zA-Z_][a-zA-Z0-9_.]*)\}\}`)
 )
@@ -388,13 +388,13 @@ func selectCLDRForm(forms map[string]string, lang string, count int, defaultTpl
 	return defaultTpl
 }
 
-// parsePluralTokenNamed extracts param name, singular and plural from {{plural:name|singular|plural}}.
-func parsePluralTokenNamed(token string) (paramName string, singular string, plural string, ok bool) {
+// parsePluralToken extracts param name and content from {{plural:name|content}}.
+func parsePluralToken(token string) (paramName string, content string, ok bool) {
 	matches := pluralPlaceholderRegex.FindStringSubmatch(token)
-	if len(matches) != 4 {
-		return "", "", "", false
+	if len(matches) != 3 {
+		return "", "", false
 	}
-	return matches[1], matches[2], matches[3], true
+	return matches[1], matches[2], true
 }
 
 func toString(value interface{}) string {
@@ -722,23 +722,53 @@ func (dmc *DefaultMessageCatalog) renderTemplate(lang string, msgKey string, tem
 	}
 
 	rendered = pluralPlaceholderRegex.ReplaceAllStringFunc(rendered, func(token string) string {
-		paramName, singular, plural, ok := parsePluralTokenNamed(token)
+		paramName, content, ok := parsePluralToken(token)
 		if !ok {
 			return token
 		}
 		val, ok := getParam(paramName)
 		if !ok {
 			return replaceMissing("plural_missing_param_"+paramName, token, paramName)
 		}
-		isOne, ok := isPluralOne(val)
+		count, ok := pluralCountFromParam(val)
 		if !ok {
 			dmc.onTemplateIssue(lang, msgKey, "plural_invalid_param_"+paramName)
 			return token
 		}
-		if isOne {
-			return singular
+
+		parts := strings.Split(content, "|")
+		// Case 1: Legacy binary plural: {{plural:count|singular|plural}}
+		if len(parts) == 2 && !strings.Contains(parts[0], ":") {
+			isOne, _ := isPluralOne(val)
+			if isOne {
+				return parts[0]
+			}
+			return parts[1]
+		}
+
+		// Case 2: Multi-form plural: {{plural:count|one:singular|few:items|many:items|other:items}}
+		forms := make(map[string]string)
+		for _, part := range parts {
+			if idx := strings.Index(part, ":"); idx > 0 {
+				formName := strings.TrimSpace(part[:idx])
+				formValue := part[idx+1:]
+				forms[formName] = formValue
+			}
 		}
-		return plural
+
+		if len(forms) > 0 {
+			form := plural.Form(lang, count)
+			if tpl, ok := forms[form]; ok {
+				return tpl
+			}
+			if tpl, ok := forms["other"]; ok {
+				return tpl
+			}
+			// fallback to first form if no match
+			return parts[0]
+		}
+
+		return token
 	})
 
 	rendered = numberPlaceholderRegex.ReplaceAllStringFunc(rendered, func(token string) string {

test/suites/msgcat/msgcat_test.go

@@ -260,6 +260,53 @@ var _ = Describe("Message Catalog", func() {
 		Expect(msgES.LongText).To(Equal("Total: 12.345,5 generado el 03/01/2026"))
 	})
 
+	It("should support multi-form plurals and advanced language rules", func() {
+		// Test English: 1 -> one, 2 -> other
+		err := messageCatalog.LoadMessages("en", []msgcat.RawMessage{{
+			Key:      "sys.multi",
+			ShortTpl: "{{plural:count|one:one item|other:{{count}} items}}",
+		}})
+		Expect(err).NotTo(HaveOccurred())
+
+		msgEN1 := messageCatalog.GetMessageWithCtx(ctx.Ctx, "sys.multi", msgcat.Params{"count": 1})
+		Expect(msgEN1.ShortText).To(Equal("one item"))
+
+		msgEN2 := messageCatalog.GetMessageWithCtx(ctx.Ctx, "sys.multi", msgcat.Params{"count": 2})
+		Expect(msgEN2.ShortText).To(Equal("2 items"))
+
+		// Test French: 0 -> one, 1 -> one, 2 -> other
+		err = messageCatalog.LoadMessages("fr", []msgcat.RawMessage{{
+			Key:      "sys.multi",
+			ShortTpl: "{{plural:count|one:un item|other:{{count}} items}}",
+		}})
+		Expect(err).NotTo(HaveOccurred())
+
+		ctx.SetValue("language", "fr")
+		msgFR0 := messageCatalog.GetMessageWithCtx(ctx.Ctx, "sys.multi", msgcat.Params{"count": 0})
+		Expect(msgFR0.ShortText).To(Equal("un item"))
+
+		msgFR1 := messageCatalog.GetMessageWithCtx(ctx.Ctx, "sys.multi", msgcat.Params{"count": 1})
+		Expect(msgFR1.ShortText).To(Equal("un item"))
+
+		msgFR2 := messageCatalog.GetMessageWithCtx(ctx.Ctx, "sys.multi", msgcat.Params{"count": 2})
+		Expect(msgFR2.ShortText).To(Equal("2 items"))
+
+		// Test Arabic: 0 -> zero, 1 -> one, 2 -> two, 3 -> few, 11 -> many, 100 -> other
+		err = messageCatalog.LoadMessages("ar", []msgcat.RawMessage{{
+			Key:      "sys.multi",
+			ShortTpl: "{{plural:count|zero:zero|one:one|two:two|few:few|many:many|other:other}}",
+		}})
+		Expect(err).NotTo(HaveOccurred())
+
+		ctx.SetValue("language", "ar")
+		Expect(messageCatalog.GetMessageWithCtx(ctx.Ctx, "sys.multi", msgcat.Params{"count": 0}).ShortText).To(Equal("zero"))
+		Expect(messageCatalog.GetMessageWithCtx(ctx.Ctx, "sys.multi", msgcat.Params{"count": 1}).ShortText).To(Equal("one"))
+		Expect(messageCatalog.GetMessageWithCtx(ctx.Ctx, "sys.multi", msgcat.Params{"count": 2}).ShortText).To(Equal("two"))
+		Expect(messageCatalog.GetMessageWithCtx(ctx.Ctx, "sys.multi", msgcat.Params{"count": 5}).ShortText).To(Equal("few"))
+		Expect(messageCatalog.GetMessageWithCtx(ctx.Ctx, "sys.multi", msgcat.Params{"count": 11}).ShortText).To(Equal("many"))
+		Expect(messageCatalog.GetMessageWithCtx(ctx.Ctx, "sys.multi", msgcat.Params{"count": 100}).ShortText).To(Equal("other"))
+	})
+
 	It("should support strict template checks and report template issues", func() {
 		observer := &mockObserver{}
 		strictCatalog, err := msgcat.NewMessageCatalog(msgcat.Config{