From 1f9321b34b0c62b8712f60f641c03a71978aa37c Mon Sep 17 00:00:00 2001
From: Snider <snider@host.uk.com>
Date: Fri, 30 Jan 2026 18:11:03 +0000
Subject: [PATCH] docs(i18n): clarify Set* behaviour and fix CurrentLanguage
 default

- CurrentLanguage() now returns "en-GB" (fallback) instead of "" when
  service is nil, consistent with other getters returning defaults
- Document why SetLanguage returns error (validates language tag) while
  SetMode, SetFormality, SetDebug do not (just set values)
- Add "Does nothing if service not initialized" to Set* doc comments

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 pkg/i18n/debug.go    |  1 +
 pkg/i18n/i18n.go     | 10 ++++++++--
 pkg/i18n/localise.go |  1 +
 3 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/pkg/i18n/debug.go b/pkg/i18n/debug.go
index ba273ac8..cc523886 100644
--- a/pkg/i18n/debug.go
+++ b/pkg/i18n/debug.go
@@ -13,6 +13,7 @@ package i18n
 // to find and update translations during development.
 
 // SetDebug enables or disables debug mode on the default service.
+// Does nothing if the service is not initialized.
 // In debug mode, translations show their keys: [key] translation
 //
 //	SetDebug(true)
diff --git a/pkg/i18n/i18n.go b/pkg/i18n/i18n.go
index 53901658..2ebab50f 100644
--- a/pkg/i18n/i18n.go
+++ b/pkg/i18n/i18n.go
@@ -61,7 +61,11 @@ func Raw(messageID string, args ...any) string {
 var ErrServiceNotInitialized = errors.New("i18n: service not initialized")
 
 // SetLanguage sets the language for the default service.
-// Returns ErrServiceNotInitialized if the service has not been initialized.
+// Returns ErrServiceNotInitialized if the service has not been initialized,
+// or an error if the language tag is invalid or unsupported.
+//
+// Unlike other Set* functions, this returns an error because it validates
+// the language tag against available locales.
 func SetLanguage(lang string) error {
 	svc := Default()
 	if svc == nil {
@@ -71,14 +75,16 @@ func SetLanguage(lang string) error {
 }
 
 // CurrentLanguage returns the current language code from the default service.
+// Returns "en-GB" (the fallback language) if the service is not initialized.
 func CurrentLanguage() string {
 	if svc := Default(); svc != nil {
 		return svc.Language()
 	}
-	return ""
+	return "en-GB"
 }
 
 // SetMode sets the translation mode for the default service.
+// Does nothing if the service is not initialized.
 func SetMode(m Mode) {
 	if svc := Default(); svc != nil {
 		svc.SetMode(m)
diff --git a/pkg/i18n/localise.go b/pkg/i18n/localise.go
index 7a3d7556..d82d2932 100644
--- a/pkg/i18n/localise.go
+++ b/pkg/i18n/localise.go
@@ -9,6 +9,7 @@ import (
 )
 
 // SetFormality sets the default formality level on the default service.
+// Does nothing if the service is not initialized.
 //
 //	SetFormality(FormalityFormal)  // Use formal address (Sie, vous)
 func SetFormality(f Formality) {