From b75dd0ae58f5f03e64c0b8f3b36f32406cc8584d Mon Sep 17 00:00:00 2001
From: Snider <snider@host.uk.com>
Date: Fri, 30 Jan 2026 18:01:02 +0000
Subject: [PATCH] refactor(i18n): fix doc comments and add package-level
 wrappers

- Remove incorrect "Panics if called on nil receiver" from chainable
  Subject methods (they actually return nil safely)
- Add Raw() as named alias for _() matching Service.Raw()
- Add package-level wrappers: SetLanguage(), CurrentLanguage(),
  SetMode(), CurrentMode()

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 pkg/i18n/compose.go |  6 ------
 pkg/i18n/i18n.go    | 41 ++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 40 insertions(+), 7 deletions(-)

diff --git a/pkg/i18n/compose.go b/pkg/i18n/compose.go
index 7b59196..f05c014 100644
--- a/pkg/i18n/compose.go
+++ b/pkg/i18n/compose.go
@@ -27,7 +27,6 @@ func NewSubject(noun string, value any) *Subject {
 
 // Count sets the count for pluralization.
 // Used to determine singular/plural forms in templates.
-// Panics if called on nil receiver; use S() to create subjects.
 //
 //	S("file", files).Count(len(files))
 func (s *Subject) Count(n int) *Subject {
@@ -40,7 +39,6 @@ func (s *Subject) Count(n int) *Subject {
 
 // Gender sets the grammatical gender for languages that require it.
 // Common values: "masculine", "feminine", "neuter"
-// Panics if called on nil receiver; use S() to create subjects.
 //
 //	S("user", user).Gender("female")
 func (s *Subject) Gender(g string) *Subject {
@@ -53,7 +51,6 @@ func (s *Subject) Gender(g string) *Subject {
 
 // In sets the location context for the subject.
 // Used in templates to provide spatial context.
-// Panics if called on nil receiver; use S() to create subjects.
 //
 //	S("file", "config.yaml").In("workspace")
 func (s *Subject) In(location string) *Subject {
@@ -66,7 +63,6 @@ func (s *Subject) In(location string) *Subject {
 
 // Formal sets the formality level to formal (Sie, vous, usted).
 // Use for polite/professional address in languages that distinguish formality.
-// Panics if called on nil receiver; use S() to create subjects.
 //
 //	S("colleague", name).Formal()
 func (s *Subject) Formal() *Subject {
@@ -79,7 +75,6 @@ func (s *Subject) Formal() *Subject {
 
 // Informal sets the formality level to informal (du, tu, tú).
 // Use for casual/friendly address in languages that distinguish formality.
-// Panics if called on nil receiver; use S() to create subjects.
 //
 //	S("friend", name).Informal()
 func (s *Subject) Informal() *Subject {
@@ -91,7 +86,6 @@ func (s *Subject) Informal() *Subject {
 }
 
 // Formality sets the formality level explicitly.
-// Panics if called on nil receiver; use S() to create subjects.
 //
 //	S("user", name).Formality(FormalityFormal)
 func (s *Subject) Formality(f Formality) *Subject {
diff --git a/pkg/i18n/i18n.go b/pkg/i18n/i18n.go
index 56352b9..aba9591 100644
--- a/pkg/i18n/i18n.go
+++ b/pkg/i18n/i18n.go
@@ -44,18 +44,57 @@ func T(messageID string, args ...any) string {
 }
 
 // _ is the raw gettext-style translation helper.
-// Unlike T(), this does NOT handle core.* namespace magic.
+// Unlike T(), this does NOT handle i18n.* namespace magic.
 // Use this for direct key lookups without auto-composition.
 //
 //	i18n._("cli.success")           // Raw lookup
 //	i18n.T("i18n.label.status")     // Smart: returns "Status:"
 func _(messageID string, args ...any) string {
+	return Raw(messageID, args...)
+}
+
+// Raw is the raw translation helper without i18n.* namespace magic.
+// Alias for _() with a more descriptive name matching Service.Raw().
+//
+//	Raw("cli.success")              // Direct lookup
+func Raw(messageID string, args ...any) string {
 	if svc := Default(); svc != nil {
 		return svc.Raw(messageID, args...)
 	}
 	return messageID
 }
 
+// SetLanguage sets the language for the default service.
+func SetLanguage(lang string) error {
+	if svc := Default(); svc != nil {
+		return svc.SetLanguage(lang)
+	}
+	return nil
+}
+
+// CurrentLanguage returns the current language code from the default service.
+func CurrentLanguage() string {
+	if svc := Default(); svc != nil {
+		return svc.Language()
+	}
+	return ""
+}
+
+// SetMode sets the translation mode for the default service.
+func SetMode(m Mode) {
+	if svc := Default(); svc != nil {
+		svc.SetMode(m)
+	}
+}
+
+// CurrentMode returns the current translation mode from the default service.
+func CurrentMode() Mode {
+	if svc := Default(); svc != nil {
+		return svc.Mode()
+	}
+	return ModeNormal
+}
+
 // N formats a number using the i18n.numeric.* namespace.
 // Wrapper for T("i18n.numeric.{format}", value).
 //