From cc66b3d049f01f2fb5a80296a451dc80efd4c5f4 Mon Sep 17 00:00:00 2001
From: Virgil <virgil@lethean.io>
Date: Fri, 3 Apr 2026 07:24:40 +0000
Subject: [PATCH] fix(i18n): add explicit article token aliases

Co-Authored-By: Virgil <virgil@lethean.io>
---
 grammar.go      | 18 ++++++++++++++++--
 grammar_test.go | 13 +++++++++++--
 2 files changed, 27 insertions(+), 4 deletions(-)

diff --git a/grammar.go b/grammar.go
index d279d59..a1e6a40 100644
--- a/grammar.go
+++ b/grammar.go
@@ -519,10 +519,12 @@ func applyRegularPlural(noun string) string {
 	return noun + "s"
 }
 
-// Article returns the appropriate article for the current language.
+// Article returns the appropriate article token for the current language.
 // English falls back to phonetic "a"/"an" heuristics. Locale grammar data
 // can override this with language-specific article forms.
 //
+// Use ArticlePhrase when you want the noun phrase prefixed with the article.
+//
 //	Article("file")     // "a"
 //	Article("error")    // "an"
 //	Article("user")     // "a" (sounds like "yoo-zer")
@@ -558,6 +560,11 @@ func Article(word string) string {
 	return "a"
 }
 
+// ArticleToken is an explicit alias for Article.
+func ArticleToken(word string) string {
+	return Article(word)
+}
+
 func articleForCurrentLanguage(lowerWord, originalWord string) (string, bool) {
 	lang := currentLangForGrammar()
 	data := grammarDataForLang(lang)
@@ -849,7 +856,7 @@ func ArticlePhrase(word string) string {
 	return prefixWithArticle(article, word)
 }
 
-// DefiniteArticle returns the language-specific definite article for a word.
+// DefiniteArticle returns the language-specific definite article token for a word.
 // For languages such as French, this respects gendered articles, plural forms,
 // and elision rules when grammar data is available.
 func DefiniteArticle(word string) string {
@@ -869,6 +876,11 @@ func DefiniteArticle(word string) string {
 	return "the"
 }
 
+// DefiniteToken is an explicit alias for DefiniteArticle.
+func DefiniteToken(word string) string {
+	return DefiniteArticle(word)
+}
+
 // DefinitePhrase prefixes a noun phrase with the correct definite article.
 func DefinitePhrase(word string) string {
 	word = core.Trim(word)
@@ -949,8 +961,10 @@ func TemplateFuncs() template.FuncMap {
 		"plural":          Pluralize,
 		"pluralForm":      PluralForm,
 		"article":         ArticlePhrase,
+		"articleToken":    ArticleToken,
 		"articlePhrase":   ArticlePhrase,
 		"definiteArticle": DefiniteArticle,
+		"definiteToken":   DefiniteToken,
 		"definite":        DefinitePhrase,
 		"definitePhrase":  DefinitePhrase,
 		"quote":           Quote,
diff --git a/grammar_test.go b/grammar_test.go
index aa23ea7..e07cbd9 100644
--- a/grammar_test.go
+++ b/grammar_test.go
@@ -354,6 +354,15 @@ func TestArticle(t *testing.T) {
 	}
 }
 
+func TestArticleTokenAliases(t *testing.T) {
+	if got, want := ArticleToken("apple"), Article("apple"); got != want {
+		t.Fatalf("ArticleToken(apple) = %q, want %q", got, want)
+	}
+	if got, want := DefiniteToken("apple"), DefiniteArticle("apple"); got != want {
+		t.Fatalf("DefiniteToken(apple) = %q, want %q", got, want)
+	}
+}
+
 func TestArticleFrenchLocale(t *testing.T) {
 	prev := Default()
 	svc, err := New()
@@ -1159,7 +1168,7 @@ func TestTemplateFuncs_Article(t *testing.T) {
 		t.Fatalf("template article = %q, want %q", got, want)
 	}
 
-	tmpl, err = template.New("").Funcs(TemplateFuncs()).Parse(`{{articlePhrase "apple"}}|{{definitePhrase "apple"}}`)
+	tmpl, err = template.New("").Funcs(TemplateFuncs()).Parse(`{{articleToken "apple"}}|{{articlePhrase "apple"}}|{{definiteToken "apple"}}|{{definitePhrase "apple"}}`)
 	if err != nil {
 		t.Fatalf("Parse() alias helpers failed: %v", err)
 	}
@@ -1169,7 +1178,7 @@ func TestTemplateFuncs_Article(t *testing.T) {
 		t.Fatalf("Execute() alias helpers failed: %v", err)
 	}
 
-	if got, want := buf.String(), "an apple|the apple"; got != want {
+	if got, want := buf.String(), "an|an apple|the|the apple"; got != want {
 		t.Fatalf("template article aliases = %q, want %q", got, want)
 	}