gui/text, guard: sixteen sentences reach a translator, and a guard asks whether they do

gen-locale.py writes the catalogue from the calls it can see, so a sentence that
stated its own words was absent from en.json - and somebody copying that file
would translate every line in it and ship a window still speaking English in
sixteen places. The existing guard asks whether a literal was born outside this
package, which is a different question and was answering correctly all along.

Two decisions about carrying a value, because until now no catalogue entry did.
Named fields rather than printf verbs: a catalogue is data, nothing compiles it,
and a translator who writes %s where the code hands a number puts
%!d(string=...) on a user's screen with nothing to catch it. And real plural
forms for the message that counts files, so a translation may carry as many
forms as its language needs - which the comment above that function has been
promising since 2026-08-12.

The boundary is drawn by the program rather than by a list: a string with no
letter in it is punctuation. The seven that carry letters are named with their
reasons, among them the sentence saying the catalogue could not be read, which
cannot come from the catalogue by definition.

All 25 stored screens render bit for bit the same, with no reference
regenerated. O130.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: donislawdev

internal/guard/catalogue_test.go

@@ -34,9 +34,12 @@ type entryInCatalogue struct {
 // stale. This is the same choice two of the boundary guards made on 2026-08-20
 // and for the same reason: where there is nothing to assert against, reading
 // what was written is better than asserting nothing.
-func englishInTheCode(t *testing.T) map[string]string {
+func englishInTheCode(t *testing.T) (map[string]string, map[string]string) {
 	t.Helper()
 	out := map[string]string{}
+	// The singular of every plural message, kept apart because only some
+	// messages have one.
+	singular := map[string]string{}
 	for _, name := range []string{"screens.go", "text.go"} {
 		path := filepath.Join("../gui/text", name)
 		file, err := parser.ParseFile(token.NewFileSet(), path, nil, 0)
@@ -49,11 +52,36 @@ func englishInTheCode(t *testing.T) map[string]string {
 				return true
 			}
 			fn, ok := call.Fun.(*ast.Ident)
-			if !ok || fn.Name != "say" || len(call.Args) != 2 {
+			if !ok {
+				return true
+			}
+			// Three ways of stating a message, and all three have to be read
+			// here. Reading only say(, which is what this did until 2026-08-26,
+			// makes every sentence carrying a value invisible to the guard -
+			// and the guard would then report the catalogue's own entries as
+			// orphans, which is how this was noticed.
+			var id, english string
+			var okID, okText bool
+			switch {
+			case fn.Name == "say" && len(call.Args) == 2:
+				id, okID = literal(call.Args[0])
+				english, okText = literal(call.Args[1])
+			case fn.Name == "sayf" && len(call.Args) == 3:
+				id, okID = literal(call.Args[0])
+				english, okText = literal(call.Args[1])
+			case fn.Name == "sayN" && len(call.Args) == 5:
+				// The plural form is what the catalogue calls "other", and it
+				// is the one this compares. The singular is checked beside it
+				// below, because a catalogue holding one of the two is worse
+				// than one holding neither: it looks complete.
+				id, okID = literal(call.Args[0])
+				english, okText = literal(call.Args[2])
+				if one, ok := literal(call.Args[1]); ok && okID {
+					singular[id] = one
+				}
+			default:
 				return true
 			}
-			id, okID := literal(call.Args[0])
-			english, okText := literal(call.Args[1])
 			if !okID || !okText {
 				t.Errorf("%s: a message is stated with something other than plain text", path)
 				return true
@@ -68,7 +96,10 @@ func englishInTheCode(t *testing.T) map[string]string {
 	if len(out) == 0 {
 		t.Fatal("no message was found in the text package, so this guard is asserting about nothing")
 	}
-	return out
+	if len(singular) == 0 {
+		t.Fatal("no message with a plural was found, so the half of this guard that reads them proves nothing")
+	}
+	return out, singular
 }
 
 func literal(e ast.Expr) (string, bool) {
@@ -94,7 +125,7 @@ func literal(e ast.Expr) (string, bool) {
 // would then be handed a file missing that sentence, translate everything in
 // it, and ship a window with one English line nobody can find the source of.
 func TestTheEnglishCatalogueSaysWhatTheCodeSays(t *testing.T) {
-	code := englishInTheCode(t)
+	code, singular := englishInTheCode(t)
 
 	raw, err := os.ReadFile(filepath.Join(localeDir, "en.json"))
 	if err != nil {
@@ -121,6 +152,12 @@ func TestTheEnglishCatalogueSaysWhatTheCodeSays(t *testing.T) {
 		if strings.TrimSpace(entry.Description) == "" {
 			t.Errorf("%s has no sentence saying where it appears", id)
 		}
+		// A plural message carries two English forms and the catalogue has to
+		// hold both. One of the two looks complete and is not.
+		if one, plural := singular[id]; plural && entry.One != one {
+			t.Errorf("%s says %q in the singular in the code and %q in the English catalogue.\n"+
+				"Run: python tools/gen-locale.py", id, one, entry.One)
+		}
 	}
 	for id := range have {
 		if _, still := code[id]; !still {

internal/guard/cataloguecoverage_test.go

@@ -0,0 +1,169 @@
+package guard
+
+import (
+	"go/ast"
+	"go/parser"
+	"go/token"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+	"testing"
+	"unicode"
+)
+
+// Every sentence the text package holds goes through the catalogue.
+//
+// There were two questions to ask about the window's words and only one was
+// being asked. TestNoWordAPersonReadsIsBornOutsideTheTextPackage asks whether a
+// literal was written OUTSIDE this package, which is about where a sentence
+// lives. This asks whether a sentence inside it ever reaches a translator, and
+// measured on 2026-08-25 the answer was no for eighteen of them - the section
+// heading over a format's settings, the line saying where the files will go, the
+// progress line, the outcome of a run. O130.
+//
+// The failure is quiet in the way this project keeps finding. gen-locale.py
+// writes the catalogue from the calls it can see, so a sentence that never calls
+// one is simply absent from en.json - and a translator copying that file gets an
+// incomplete one with nothing to say so. They would translate every line in it
+// and ship a window still speaking English in eighteen places.
+//
+// The rule, decided with the owner on 2026-08-26: anything that reads as
+// language goes through the catalogue. A separator does not, and nothing that
+// carries no letter at all is language - which is a line a program can draw, so
+// the punctuation looks after itself and the list below only holds the awkward
+// cases.
+var notThroughTheCatalogue = map[string]string{
+	"WindowTitle":             "the name of the program, which is not translated. It is the same three words in every language, and a catalogue entry for it would be an invitation to change them.",
+	"HeadingAbout":            "the same name again, at the top of the About screen. Same reason.",
+	"CatalogueNotLoaded":      "the sentence saying the catalogue could not be read. It cannot come from the catalogue - that is what it is about - so this one is English wherever it appears, and it is written to a terminal rather than to the window.",
+	"NoWindowInThisBuild":     "written to standard error by a window binary with no window in it, so it is terminal text and D9 keeps the terminal English forever.",
+	"ExactBytes":              "the byte symbol, which follows what the command line prints rather than the language of the window - the comment above it says so. Translating one and not the other would make two numbers on one screen disagree about their unit.",
+	"PlaceholderNameTemplate": "an example of a file name template, so it is a value somebody could type rather than a sentence. Translating it would produce an example that does not work.",
+	"SupportURL":              "an address.",
+}
+
+// wordsIn is every string literal a declaration states for itself, ignoring the
+// ones handed to the catalogue.
+//
+// Only literals carrying a letter. A separator, a mark and a piece of spacing
+// are punctuation in every language, and a rule that demanded catalogue entries
+// for them would fill a translator's file with lines to copy unchanged - which
+// is the opposite of what an inventory is for.
+func wordsIn(node ast.Node) []string {
+	var found []string
+	ast.Inspect(node, func(n ast.Node) bool {
+		if call, ok := n.(*ast.CallExpr); ok {
+			if fn, ok := call.Fun.(*ast.Ident); ok {
+				switch fn.Name {
+				case "say", "sayf", "sayN":
+					// The English inside a catalogue call is the entry itself.
+					// Its other arguments are still walked, because a sentence
+					// built out of a second literal on the way in would be a
+					// sentence the catalogue never sees.
+					for i, arg := range call.Args {
+						if i == 0 {
+							continue
+						}
+						if _, isLit := arg.(*ast.BasicLit); isLit {
+							continue
+						}
+						found = append(found, wordsIn(arg)...)
+					}
+					return false
+				}
+			}
+		}
+		// The key of a map entry is a placeholder name, not language. It has to
+		// match the spelling inside the sentence exactly, so translating it
+		// would break the sentence rather than translate it - the values beside
+		// it are still walked.
+		if kv, ok := n.(*ast.KeyValueExpr); ok {
+			found = append(found, wordsIn(kv.Value)...)
+			return false
+		}
+		lit, ok := n.(*ast.BasicLit)
+		if !ok || lit.Kind != token.STRING {
+			return true
+		}
+		value, err := strconv.Unquote(lit.Value)
+		if err != nil || !strings.ContainsFunc(value, unicode.IsLetter) {
+			return true
+		}
+		found = append(found, value)
+		return true
+	})
+	return found
+}
+
+func TestEverySentenceInTheTextPackageGoesThroughTheCatalogue(t *testing.T) {
+	checked, offenders := 0, map[string][]string{}
+	for _, name := range []string{"screens.go", "text.go"} {
+		path := filepath.Join("../gui/text", name)
+		file, err := parser.ParseFile(token.NewFileSet(), path, nil, 0)
+		if err != nil {
+			t.Fatalf("%s: %v", path, err)
+		}
+		for _, decl := range file.Decls {
+			switch d := decl.(type) {
+			case *ast.FuncDecl:
+				checked++
+				if words := wordsIn(d.Body); len(words) > 0 {
+					offenders[d.Name.Name] = words
+				}
+			case *ast.GenDecl:
+				// Constants and variables as well as functions. A sentence held
+				// as a constant is read by exactly the same person.
+				for _, spec := range d.Specs {
+					value, ok := spec.(*ast.ValueSpec)
+					if !ok {
+						continue
+					}
+					for i, ident := range value.Names {
+						checked++
+						if i >= len(value.Values) {
+							continue
+						}
+						if words := wordsIn(value.Values[i]); len(words) > 0 {
+							offenders[ident.Name] = words
+						}
+					}
+				}
+			}
+		}
+	}
+	if checked == 0 {
+		t.Fatal("no declaration was read in the text package, so this guard checked nothing")
+	}
+
+	var unexplained, stale []string
+	for name := range offenders {
+		if _, allowed := notThroughTheCatalogue[name]; !allowed {
+			unexplained = append(unexplained, name)
+		}
+	}
+	// An allowance for something that now goes through the catalogue is an
+	// allowance nobody needs, and a list nobody prunes is where this drift
+	// would hide next - the same rule the regression table guard keeps.
+	for name := range notThroughTheCatalogue {
+		if _, still := offenders[name]; !still {
+			stale = append(stale, name)
+		}
+	}
+	sort.Strings(unexplained)
+	sort.Strings(stale)
+
+	for _, name := range unexplained {
+		t.Errorf("%s states %q itself, so it never reaches a translator.\n"+
+			"Reason: gen-locale.py writes the catalogue from the calls it can see, so this sentence\n"+
+			"is absent from en.json and a translator copying that file is handed an incomplete one\n"+
+			"with nothing to say so.\n"+
+			"What to do: state it with say, sayf or sayN - or name it in notThroughTheCatalogue and\n"+
+			"say why it is not language.", name, offenders[name])
+	}
+	for _, name := range stale {
+		t.Errorf("%s is excused from the catalogue and no longer needs to be.\n"+
+			"What to do: take it off notThroughTheCatalogue.", name)
+	}
+	t.Logf("%d declaration(s) read, %d hold words of their own, all of them named", checked, len(offenders))
+}

internal/gui/text/catalogue.go

@@ -5,6 +5,8 @@ import (
 	"encoding/json"
 	"io/fs"
 	"path"
+	"strings"
+	"text/template"
 
 	"github.com/nicksnyder/go-i18n/v2/i18n"
 	"golang.org/x/text/language"
@@ -48,6 +50,92 @@ var builtIn embed.FS
 // translations. See docs/STACK.md.
 var localiser *i18n.Localizer
 
+// sayf is say for a sentence that has values in it.
+//
+// Named fields rather than the printf verbs the rest of this tool writes, and
+// the reason is rule 6 rather than taste. A catalogue is DATA: it arrives as a
+// file, nothing compiles it, and no test of ours stands between it and the
+// window. A translator who writes %s where the code hands a number puts
+// "%!d(string=...)" on somebody's screen at run time and nothing says a word. A
+// named field cannot be the wrong type, and one that is missing renders as
+// "<no value>" - wrong, but visible.
+//
+// Decided with the owner on 2026-08-26. The printf spelling was the cheaper of
+// the two and was turned down: the generator already reads it, the call sites
+// stay one line, and the failure it allows is silent and lands on a user.
+//
+// The fallback renders the English with the same template engine rather than
+// returning it raw, because a sentence with {{.Directory}} still in it is not a
+// fallback, it is a different defect.
+func sayf(id, english string, data map[string]any) string {
+	if localiser == nil {
+		return fill(english, data)
+	}
+	out, err := localiser.Localize(&i18n.LocalizeConfig{
+		MessageID:      id,
+		DefaultMessage: &i18n.Message{ID: id, Other: english},
+		TemplateData:   data,
+	})
+	if err != nil {
+		return fill(english, data)
+	}
+	return out
+}
+
+// sayN is sayf where a count chooses the form of the sentence.
+//
+// English has two forms and Polish has three, and the library knows which rule
+// belongs to which language - so this hands over both English forms and the
+// number, and a translator's file may carry as many forms as their language
+// needs. Writing "1 file" and "%d files" as two flat entries would have put a
+// thing into the catalogue that is broken for Polish before anybody starts,
+// with no way to fix it from a translation file.
+//
+// The count is always available to the sentence as Count, because a plural form
+// that cannot say the number is not much use.
+func sayN(id, one, other string, count int, data map[string]any) string {
+	values := map[string]any{"Count": count}
+	for k, v := range data {
+		values[k] = v
+	}
+	if localiser == nil {
+		if count == 1 {
+			return fill(one, values)
+		}
+		return fill(other, values)
+	}
+	out, err := localiser.Localize(&i18n.LocalizeConfig{
+		MessageID:      id,
+		DefaultMessage: &i18n.Message{ID: id, One: one, Other: other},
+		PluralCount:    count,
+		TemplateData:   values,
+	})
+	if err != nil {
+		if count == 1 {
+			return fill(one, values)
+		}
+		return fill(other, values)
+	}
+	return out
+}
+
+// fill puts the values into a sentence without the catalogue.
+//
+// Both failures return the layout untouched rather than an empty string: a
+// sentence with its placeholders showing is readable and says something is
+// wrong, and nothing at all says the window is broken.
+func fill(layout string, data map[string]any) string {
+	t, err := template.New("").Parse(layout)
+	if err != nil {
+		return layout
+	}
+	var out strings.Builder
+	if err := t.Execute(&out, data); err != nil {
+		return layout
+	}
+	return out.String()
+}
+
 // say is what every entry in this package asks, and what makes the English
 // beside it a default rather than the answer.
 //