Add i18n package

Author: adrianpk

docs/features.md

@@ -13,11 +13,13 @@
 | Package | Description |
 |---------|-------------|
 | `web` | Chi router helpers, response utilities, flash messages |
-| `middleware` | Request ID, role-based access, middleware stack, IP-based rate limiting |
-| `render` | Template FuncMap utilities |
+| `middleware` | Request ID, role-based access, rate limiting, locale detection, static cache |
+| `render` | Template FuncMap utilities, i18n integration |
 | `render/ui` | UI components (Badge, Chip, Price, Stat), dynamic currency registration |
 | `modal` | Modal dialog configuration |
 | `pagination` | Generic pagination (`Result[T]`) |
+| `i18n` | Internationalization with YAML translation files |
+| `settings` | Runtime key-value configuration with schema validation |
 
 ## Auth & Security
 

i18n/i18n.go

@@ -0,0 +1,152 @@
+package i18n
+
+import (
+	"embed"
+	"fmt"
+	"strings"
+	"sync"
+
+	"gopkg.in/yaml.v3"
+)
+
+const DefaultLocale = "en"
+
+type Translator struct {
+	translations map[string]map[string]any
+	mu           sync.RWMutex
+	defaultLoc   string
+	available    []string
+}
+
+func New() *Translator {
+	return &Translator{
+		translations: make(map[string]map[string]any),
+		defaultLoc:   DefaultLocale,
+		available:    []string{},
+	}
+}
+
+func (t *Translator) LoadFromFS(fs embed.FS, basePath string) error {
+	entries, err := fs.ReadDir(basePath)
+	if err != nil {
+		return fmt.Errorf("read i18n directory: %w", err)
+	}
+
+	for _, entry := range entries {
+		if entry.IsDir() {
+			continue
+		}
+
+		name := entry.Name()
+		if !strings.HasSuffix(name, ".yml") && !strings.HasSuffix(name, ".yaml") {
+			continue
+		}
+
+		locale := strings.TrimSuffix(strings.TrimSuffix(name, ".yml"), ".yaml")
+		filePath := basePath + "/" + name
+
+		data, err := fs.ReadFile(filePath)
+		if err != nil {
+			return fmt.Errorf("read %s: %w", filePath, err)
+		}
+
+		if err := t.loadLocale(locale, data); err != nil {
+			return fmt.Errorf("parse %s: %w", filePath, err)
+		}
+
+		t.available = append(t.available, locale)
+	}
+
+	return nil
+}
+
+func (t *Translator) loadLocale(locale string, data []byte) error {
+	var raw map[string]any
+	if err := yaml.Unmarshal(data, &raw); err != nil {
+		return err
+	}
+
+	t.mu.Lock()
+	defer t.mu.Unlock()
+
+	t.translations[locale] = make(map[string]any)
+	flatten("", raw, t.translations[locale])
+
+	return nil
+}
+
+func flatten(prefix string, src map[string]any, dest map[string]any) {
+	for k, v := range src {
+		key := k
+		if prefix != "" {
+			key = prefix + "." + k
+		}
+
+		switch val := v.(type) {
+		case map[string]any:
+			flatten(key, val, dest)
+		default:
+			dest[key] = val
+		}
+	}
+}
+
+func (t *Translator) Get(locale, key string) string {
+	t.mu.RLock()
+	defer t.mu.RUnlock()
+
+	if trans, ok := t.translations[locale]; ok {
+		if val, ok := trans[key]; ok {
+			if s, ok := val.(string); ok {
+				return s
+			}
+			return fmt.Sprintf("%v", val)
+		}
+	}
+
+	if locale != t.defaultLoc {
+		if trans, ok := t.translations[t.defaultLoc]; ok {
+			if val, ok := trans[key]; ok {
+				if s, ok := val.(string); ok {
+					return s
+				}
+				return fmt.Sprintf("%v", val)
+			}
+		}
+	}
+
+	return key
+}
+
+func (t *Translator) SetDefaultLocale(locale string) {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	t.defaultLoc = locale
+}
+
+func (t *Translator) DefaultLocaleValue() string {
+	t.mu.RLock()
+	defer t.mu.RUnlock()
+	return t.defaultLoc
+}
+
+func (t *Translator) AvailableLocales() []string {
+	t.mu.RLock()
+	defer t.mu.RUnlock()
+	result := make([]string, len(t.available))
+	copy(result, t.available)
+	return result
+}
+
+func (t *Translator) HasLocale(locale string) bool {
+	t.mu.RLock()
+	defer t.mu.RUnlock()
+	_, ok := t.translations[locale]
+	return ok
+}
+
+func (t *Translator) TranslateFunc(locale string) func(string) string {
+	return func(key string) string {
+		return t.Get(locale, key)
+	}
+}

i18n/i18n_test.go

@@ -0,0 +1,138 @@
+package i18n
+
+import (
+	"embed"
+	"testing"
+)
+
+//go:embed testdata
+var testFS embed.FS
+
+func TestTranslatorLoadFromFS(t *testing.T) {
+	tr := New()
+	err := tr.LoadFromFS(testFS, "testdata")
+	if err != nil {
+		t.Fatalf("LoadFromFS failed: %v", err)
+	}
+
+	if !tr.HasLocale("en") {
+		t.Error("expected locale 'en' to be loaded")
+	}
+	if !tr.HasLocale("es") {
+		t.Error("expected locale 'es' to be loaded")
+	}
+}
+
+func TestTranslatorGet(t *testing.T) {
+	tr := New()
+	if err := tr.LoadFromFS(testFS, "testdata"); err != nil {
+		t.Fatalf("LoadFromFS failed: %v", err)
+	}
+
+	tests := []struct {
+		name     string
+		locale   string
+		key      string
+		expected string
+	}{
+		{
+			name:     "simple key in english",
+			locale:   "en",
+			key:      "common.search",
+			expected: "Search",
+		},
+		{
+			name:     "simple key in spanish",
+			locale:   "es",
+			key:      "common.search",
+			expected: "Buscar",
+		},
+		{
+			name:     "nested key",
+			locale:   "en",
+			key:      "user.name",
+			expected: "Name",
+		},
+		{
+			name:     "fallback to english when key missing in locale",
+			locale:   "es",
+			key:      "user.only_english",
+			expected: "Only in English",
+		},
+		{
+			name:     "missing key returns key itself",
+			locale:   "en",
+			key:      "missing.key.path",
+			expected: "missing.key.path",
+		},
+		{
+			name:     "unknown locale falls back to english",
+			locale:   "fr",
+			key:      "common.search",
+			expected: "Search",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := tr.Get(tt.locale, tt.key)
+			if result != tt.expected {
+				t.Errorf("Get(%q, %q) = %q, want %q", tt.locale, tt.key, result, tt.expected)
+			}
+		})
+	}
+}
+
+func TestTranslatorAvailableLocales(t *testing.T) {
+	tr := New()
+	if err := tr.LoadFromFS(testFS, "testdata"); err != nil {
+		t.Fatalf("LoadFromFS failed: %v", err)
+	}
+
+	locales := tr.AvailableLocales()
+	if len(locales) < 2 {
+		t.Errorf("expected at least 2 locales, got %d", len(locales))
+	}
+
+	found := make(map[string]bool)
+	for _, loc := range locales {
+		found[loc] = true
+	}
+
+	if !found["en"] {
+		t.Error("expected 'en' in available locales")
+	}
+	if !found["es"] {
+		t.Error("expected 'es' in available locales")
+	}
+}
+
+func TestTranslatorSetDefaultLocale(t *testing.T) {
+	tr := New()
+	if err := tr.LoadFromFS(testFS, "testdata"); err != nil {
+		t.Fatalf("LoadFromFS failed: %v", err)
+	}
+
+	tr.SetDefaultLocale("es")
+	if tr.DefaultLocaleValue() != "es" {
+		t.Errorf("expected default locale 'es', got %q", tr.DefaultLocaleValue())
+	}
+
+	result := tr.Get("fr", "common.search")
+	if result != "Buscar" {
+		t.Errorf("expected Spanish fallback 'Buscar', got %q", result)
+	}
+}
+
+func TestTranslatorTranslateFunc(t *testing.T) {
+	tr := New()
+	if err := tr.LoadFromFS(testFS, "testdata"); err != nil {
+		t.Fatalf("LoadFromFS failed: %v", err)
+	}
+
+	fn := tr.TranslateFunc("es")
+	result := fn("common.search")
+	if result != "Buscar" {
+		t.Errorf("TranslateFunc(es)(common.search) = %q, want 'Buscar'", result)
+	}
+}

i18n/readme.md

@@ -0,0 +1,44 @@
+# i18n
+
+Internationalization support with YAML translation files.
+
+## Usage
+
+```go
+//go:embed locales
+var localesFS embed.FS
+
+// Load translations
+translator := i18n.New()
+translator.LoadFromFS(localesFS, "locales")
+
+// Get translation
+text := translator.Get("es", "common.search") // "Buscar"
+
+// Fallback to default locale if key missing
+text := translator.Get("es", "missing.key") // returns key itself
+
+// Template function
+fn := translator.TranslateFunc("es")
+fn("common.search") // "Buscar"
+
+// Check available locales
+locales := translator.AvailableLocales() // ["en", "es"]
+translator.HasLocale("de") // false
+```
+
+## Translation Files
+
+YAML files named by locale (e.g., `en.yml`, `es.yml`):
+
+```yaml
+common:
+  search: "Search"
+  back: "Back"
+
+user:
+  name: "Name"
+  email: "Email"
+```
+
+Access via dot notation: `common.search`, `user.name`.

i18n/testdata/en.yml

@@ -0,0 +1,14 @@
+common:
+  search: "Search"
+  back: "Back"
+  submit: "Submit"
+
+user:
+  name: "Name"
+  email: "Email"
+  role: "Role"
+  only_english: "Only in English"
+
+actions:
+  save: "Save"
+  delete: "Delete"

i18n/testdata/es.yml

@@ -0,0 +1,13 @@
+common:
+  search: "Buscar"
+  back: "Volver"
+  submit: "Enviar"
+
+user:
+  name: "Nombre"
+  email: "Correo"
+  role: "Rol"
+
+actions:
+  save: "Guardar"
+  delete: "Eliminar"

middleware/cache.go

@@ -0,0 +1,12 @@
+package middleware
+
+import "net/http"
+
+// StaticCache adds aggressive cache headers for static assets.
+// Safe for content-addressed files where URLs change when content changes.
+func StaticCache(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Cache-Control", "public, max-age=31536000, immutable")
+		next.ServeHTTP(w, r)
+	})
+}