tools: align locale diagnostics and generate native language names

tools/cli/upstream.go

@@ -20,11 +20,7 @@ func UpstreamCommand() *cli.Command {
 				return err
 			}
 			logging.Info("Upstream", "%s: %d mail files, %d languages", s.Lock.Tag, len(s.Templates), len(s.Locales))
-			for _, lang := range s.Languages() {
-				if keys := missing[lang]; len(keys) > 0 {
-					logging.Warn("Locale", "%s -> en-US: %v", lang, keys)
-				}
-			}
+			logging.WarnMissingTranslations(missing)
 			return nil
 		}},
 	}}

tools/go.mod

@@ -5,6 +5,7 @@ go 1.24.0
 require (
 	github.com/urfave/cli/v2 v2.27.7
 	golang.org/x/net v0.46.0
+	golang.org/x/text v0.31.0
 )
 
 require (

tools/go.sum

@@ -8,3 +8,5 @@ github.com/xrash/smetrics v0.0.0-20240521201337-686a1a2994c1 h1:gEOO8jv9F4OT7lGC
 github.com/xrash/smetrics v0.0.0-20240521201337-686a1a2994c1/go.mod h1:Ohn+xnUBiLI6FVj/9LpzZWtj1/D6lUovWYBkxHVV3aM=
 golang.org/x/net v0.46.0 h1:giFlY12I07fugqwPuWJi68oOnpfqFnJIJzaIIm2JVV4=
 golang.org/x/net v0.46.0/go.mod h1:Q9BGdFy1y4nkUwiLvT5qtyhAnEHgnQ/zd8PfU6nc210=
+golang.org/x/text v0.31.0 h1:aC8ghyu4JhP8VojJ2lEHBnochRno1sgL6nEi9WGFGMM=
+golang.org/x/text v0.31.0/go.mod h1:tKRAlv61yKIjGGHX/4tP1LTbc13YSec1pxVEWXzfoeM=

tools/logging/locale.go

@@ -0,0 +1,43 @@
+package logging
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+)
+
+// WarnMissingTranslations groups missing keys without wrapping long key lists.
+func WarnMissingTranslations(missing map[string][]string) {
+	if message := missingTranslations(missing); message != "" {
+		Warn("Locale", "%s", message)
+	}
+}
+
+func missingTranslations(missing map[string][]string) string {
+	languages := make([]string, 0, len(missing))
+	width := len("Language")
+	for lang, keys := range missing {
+		if len(keys) > 0 {
+			languages = append(languages, lang)
+			width = max(width, len(lang))
+		}
+	}
+	if len(languages) == 0 {
+		return ""
+	}
+	sort.Strings(languages)
+	var message strings.Builder
+	fmt.Fprintf(&message, "Missing translation keys:\n%-*s  %-8s  %s\n", width, "Language", "Fallback", "Key")
+	for _, lang := range languages {
+		keys := append([]string(nil), missing[lang]...)
+		sort.Strings(keys)
+		for i, key := range keys {
+			label, fallback := "", ""
+			if i == 0 {
+				label, fallback = lang, "en-US"
+			}
+			fmt.Fprintf(&message, "%-*s  %-8s  %s\n", width, label, fallback, key)
+		}
+	}
+	return strings.TrimSuffix(message.String(), "\n")
+}

tools/logging/locale_test.go

@@ -0,0 +1,38 @@
+package logging
+
+import (
+	"bytes"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+func TestMissingTranslations(t *testing.T) {
+	missing := map[string][]string{
+		"fr-FR": {"mail.second", "mail.first"},
+		"en-US": nil,
+		"de-DE": {"mail.first"},
+	}
+	want := "Missing translation keys:\n" +
+		"Language  Fallback  Key\n" +
+		"de-DE     en-US     mail.first\n" +
+		"fr-FR     en-US     mail.first\n" +
+		"                    mail.second"
+	message := missingTranslations(missing)
+	if message != want {
+		t.Fatalf("got %q, want %q", message, want)
+	}
+	if !reflect.DeepEqual(missing["fr-FR"], []string{"mail.second", "mail.first"}) {
+		t.Fatal("report mutated input keys")
+	}
+	var output bytes.Buffer
+	write(&output, true, "W", "Locale", message)
+	for _, line := range strings.Split(strings.TrimSuffix(output.String(), "\n"), "\n") {
+		if !strings.HasPrefix(line, "\033[33m[W]\033[0m [Locale] ") {
+			t.Fatalf("missing warning prefix: %q", line)
+		}
+	}
+	if missingTranslations(nil) != "" || missingTranslations(map[string][]string{"en-US": nil}) != "" {
+		t.Fatal("empty report produced a warning")
+	}
+}

tools/preview/engine.go

@@ -20,16 +20,17 @@ import (
 )
 
 type PreviewResult struct {
-	Rendered  map[string]map[string]map[string]string
-	Registry  map[string]map[string]string
-	Params    map[string]map[string]string
-	Languages []string
-	Themes    []string
-	Upstream  string
-	Commit    string
-	Logo      []byte
-	Fallback  map[string][]string
-	Warnings  map[string]map[string][]string
+	Rendered      map[string]map[string]map[string]string
+	Registry      map[string]map[string]string
+	Params        map[string]map[string]string
+	Languages     []string
+	LanguageNames map[string]string
+	Themes        []string
+	Upstream      string
+	Commit        string
+	Logo          []byte
+	Fallback      map[string][]string
+	Warnings      map[string]map[string][]string
 }
 
 func DiscoverThemes(dir string) ([]string, error) { return builder.Discover(dir) }
@@ -92,6 +93,7 @@ func RenderAll(themesDir string, cfg *config.TemplatesConfig, filter map[string]
 		return nil, err
 	}
 	result := &PreviewResult{Rendered: map[string]map[string]map[string]string{}, Registry: config.Registry(cfg), Params: map[string]map[string]string{}, Languages: s.Languages(), Upstream: s.Lock.Tag, Fallback: missing, Warnings: map[string]map[string][]string{}}
+	result.LanguageNames = languageNames(result.Languages)
 	for id, t := range cfg.Templates {
 		result.Params[id] = config.FlattenParams(t.Params)
 	}
@@ -236,6 +238,7 @@ func WriteRenderedJS(result *PreviewResult, output string) error {
 		return err
 	}
 	manifest := map[string]any{"schema": 1, "upstream": result.Upstream, "languages": result.Languages, "themes": result.Themes, "registry": result.Registry, "params": result.Params, "fallback": result.Fallback, "warnings": result.Warnings}
+	manifest["language_names"] = result.LanguageNames
 	manifest["logo"] = "data:image/png;base64," + base64.StdEncoding.EncodeToString(result.Logo)
 	manifest["upstream_commit"] = result.Commit
 	data, err := json.Marshal(manifest)
@@ -267,10 +270,8 @@ func PrintDetailedSummary(result *PreviewResult, _ string, _ *config.TemplatesCo
 				logging.Warn("Upstream", "%s", strings.TrimPrefix(warning, "[UPSTREAM-WARN] "))
 			}
 		}
-		if keys := result.Fallback[lang]; len(keys) > 0 {
-			logging.Warn("Locale", "%s -> en-US: %s", lang, strings.Join(keys, ", "))
-		}
 	}
+	logging.WarnMissingTranslations(result.Fallback)
 }
 
 func markSafeHTML(data map[string]any) {

tools/preview/languages.go

@@ -0,0 +1,21 @@
+package preview
+
+import (
+	"golang.org/x/text/language"
+	"golang.org/x/text/language/display"
+)
+
+// languageNames derives native names from CLDR for the generated preview locales.
+func languageNames(locales []string) map[string]string {
+	names := make(map[string]string, len(locales))
+	for _, locale := range locales {
+		name := locale
+		if tag, err := language.Parse(locale); err == nil {
+			if native := display.Self.Name(tag); native != "" {
+				name = native
+			}
+		}
+		names[locale] = name
+	}
+	return names
+}

tools/preview/languages_test.go

@@ -0,0 +1,33 @@
+package preview
+
+import (
+	"path/filepath"
+	"testing"
+
+	"gitea-mail-templates/tools/upstream"
+)
+
+func TestNativeLanguageNames(t *testing.T) {
+	snapshot, err := upstream.LoadPinned(filepath.Join("..", ".."))
+	if err != nil {
+		t.Fatal(err)
+	}
+	locales := snapshot.Languages()
+	names := languageNames(locales)
+	if len(names) != len(locales) {
+		t.Fatal("language names do not match preview locales")
+	}
+	for _, locale := range locales {
+		if names[locale] == "" || names[locale] == locale {
+			t.Errorf("missing native name for %s", locale)
+		}
+	}
+	for locale, want := range map[string]string{"ga-IE": "Gaeilge", "is-IS": "íslenska"} {
+		if names[locale] != want {
+			t.Errorf("%s: got %q, want %q", locale, names[locale], want)
+		}
+	}
+	if got := languageNames([]string{"!invalid"})["!invalid"]; got != "!invalid" {
+		t.Fatalf("invalid locale fallback: %q", got)
+	}
+}

tools/preview/parity_test.go

@@ -294,6 +294,7 @@ func TestSubjectSplitAndMissingFixture(t *testing.T) {
 
 func TestPreviewBundles(t *testing.T) {
 	result := &PreviewResult{Rendered: map[string]map[string]map[string]string{"en-US": {"test": {"activate": "<body>hello</body>"}}, "zh-CN": {"test": {"activate": "<body>你好</body>"}}}, Languages: []string{"en-US", "zh-CN"}, Themes: []string{"test"}, Registry: map[string]map[string]string{}, Upstream: "v28.0.0"}
+	result.LanguageNames = languageNames(result.Languages)
 	output := filepath.Join(t.TempDir(), "rendered.js")
 	if err := WriteRenderedJS(result, output); err != nil {
 		t.Fatal(err)
@@ -305,6 +306,9 @@ func TestPreviewBundles(t *testing.T) {
 	if bytes.Contains(manifest, []byte("<body>")) {
 		t.Fatal("manifest embeds mail payload")
 	}
+	if !bytes.Contains(manifest, []byte(`"language_names":`)) || !bytes.Contains(manifest, []byte(fmt.Sprintf("%q:%q", "en-US", result.LanguageNames["en-US"]))) {
+		t.Fatal("manifest does not include generated native language names")
+	}
 	for _, lang := range result.Languages {
 		data, err := os.ReadFile(filepath.Join(filepath.Dir(output), "rendered", lang+".js"))
 		if err != nil {

tools/upstream/keys.go

@@ -11,7 +11,12 @@ import (
 // TrN keys. Dynamic translation keys require an explicit adapter review.
 func ReferencedKeys(s *Snapshot) ([]string, error) {
 	fns := template.FuncMap{}
-	for _, name := range []string{"AppUrl", "AppName", "AppDomain", "DotEscape", "QueryEscape", "ShortSha", "HTMLFormat", "PathEscapeSegments", "FormatByteSize", "Dict", "dict", "StringUtils", "SliceUtils", "JsonUtils", "QueryBuild", "PathEscape", "SanitizeHTML"} {
+	for _, name := range []string{
+		"AppUrl", "AppName", "AppDomain", "DotEscape", "QueryEscape",
+		"ShortSha", "HTMLFormat", "PathEscapeSegments", "FormatByteSize",
+		"Dict", "dict", "StringUtils", "SliceUtils", "JsonUtils", "QueryBuild",
+		"PathEscape", "SanitizeHTML"} {
+
 		fns[name] = func(...any) string { return "" }
 	}
 	keys := map[string]bool{}