Grammar Table Contract

Sacred Rule

Agents MUST NOT flatten locale JSON files. The grammar engine depends on the nested gram.* structure. Flattening (converting nested objects to dot-notation strings) breaks the grammar engine silently.

en.json Structure

The locale file contains two distinct sections:

1. Grammar Tables (`gram.*` namespace)

These power the forward composition and reverse tokeniser:

{
  "gram": {
    "verb": {
      "delete": { "past": "deleted", "gerund": "deleting" },
      "run":    { "past": "ran", "gerund": "running" },
      "build":  { "past": "built", "gerund": "building" }
    },
    "noun": {
      "file":   { "plural": "files" },
      "child":  { "plural": "children" },
      "status": { "plural": "statuses" }
    },
    "article": {
      "rules": {
        "vowel_prefix": "an",
        "default": "a",
        "definite": "the"
      }
    },
    "punct": {
      "label_suffix": ":",
      "progress_suffix": "...",
      "question_suffix": "?"
    },
    "word": {
      "url": "technical",
      "api": "technical",
      "ssh": "technical"
    }
  }
}

2. Translation Messages (everything else)

Consumer-provided translations. go-i18n provides the lookup mechanism but does NOT ship these:

{
  "cli.success": "Operation completed successfully",
  "cli.error.not_found": "{{.Name}} not found"
}

Key Contracts

Rule	Reason
`gram.verb.*` must have `past` and `gerund` keys	Forward composition uses both
`gram.noun.*` must have `plural` key	Pluralize() reads this
Values must be the inflected form, not rules	"deleted" not "d suffix"
Irregular forms override regular rules	Tier 1/2 checked before Tier 3
Regular morphology is fallback only	Applied when no gram.* entry exists
Round-trip must hold	PastTense(base) then reverse must recover base

Adding a New Language

Create locales/{lang}.json with gram.* section
Populate gram.verb with irregular verbs for that language
Populate gram.noun with irregular nouns
Define gram.article rules (if language has articles)
Define gram.punct (language-specific punctuation)
Add CLDR plural rules in language.go if not already present
Run reversal round-trip tests to verify bijective property