docs(i18n): add semantic i18n system design
Design document for extending i18n with: - Reserved namespaces (common.*, core.*) - Semantic intents with metadata (_meta) - Transmute() for composite translations - CLI integration (Confirm, Question, Choose) - Template functions (title, past, plural, etc.) - Subject helper with count/gender support Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Snider
parent
6f6ee99008
commit
1f75cd8b40
1 changed files with 327 additions and 0 deletions
327
docs/plans/2026-01-30-semantic-i18n-design.md
Normal file
327
docs/plans/2026-01-30-semantic-i18n-design.md
Normal file
|
|
@ -0,0 +1,327 @@
|
|||
# Semantic i18n System Design
|
||||
|
||||
## Overview
|
||||
|
||||
Extend the i18n system beyond simple key-value translation to support **semantic intents** that encode meaning, enabling:
|
||||
|
||||
- Composite translations from reusable fragments
|
||||
- Grammatical awareness (gender, plurality, formality)
|
||||
- CLI prompt integration with localized options
|
||||
- Reduced calling code complexity
|
||||
|
||||
## Goals
|
||||
|
||||
1. **Simple cases stay simple** - `_("key")` works as expected
|
||||
2. **Complex cases become declarative** - Intent drives output, not caller logic
|
||||
3. **Translators have power** - Grammar rules live in translations, not code
|
||||
4. **CLI integration** - Questions, confirmations, choices are first-class
|
||||
|
||||
## API Design
|
||||
|
||||
### Translation Functions
|
||||
|
||||
```go
|
||||
// Simple lookup (gettext-style) - unchanged
|
||||
i18n._("cli.success")
|
||||
i18n._("common.label.error")
|
||||
|
||||
// Opinionated lookup with namespace awareness
|
||||
i18n.T("core.edit.question", i18n.Subject("file", path))
|
||||
|
||||
// Transform with semantic intent
|
||||
i18n.Transmute("core.edit", map[string]any{
|
||||
"Subject": path,
|
||||
"Count": 1,
|
||||
})
|
||||
```
|
||||
|
||||
### CLI Integration
|
||||
|
||||
```go
|
||||
// Simple yes/no with localized options
|
||||
confirmed := cli.Confirm("core.delete", i18n.Subject("file", path))
|
||||
// Displays: "Delete /path/to/file.txt? [y/N]"
|
||||
// Returns: bool
|
||||
|
||||
// Question with custom options
|
||||
choice := cli.Question("core.save", i18n.Subject("changes", 3), cli.Options{
|
||||
Default: "yes",
|
||||
Extra: []string{"all"}, // Adds [a] option
|
||||
})
|
||||
// Displays: "Save 3 changes? [a/y/N]"
|
||||
// Returns: "yes" | "no" | "all"
|
||||
|
||||
// Choice from list
|
||||
selected := cli.Choose("core.select.branch", branches)
|
||||
// Displays localized prompt with arrow selection
|
||||
```
|
||||
|
||||
## Reserved Namespaces
|
||||
|
||||
### `common.*` - Reusable Fragments
|
||||
|
||||
Atomic translation units that can be composed:
|
||||
|
||||
```json
|
||||
{
|
||||
"common": {
|
||||
"verb": {
|
||||
"edit": "edit",
|
||||
"delete": "delete",
|
||||
"create": "create",
|
||||
"save": "save",
|
||||
"update": "update"
|
||||
},
|
||||
"noun": {
|
||||
"file": { "one": "file", "other": "files" },
|
||||
"commit": { "one": "commit", "other": "commits" },
|
||||
"change": { "one": "change", "other": "changes" }
|
||||
},
|
||||
"article": {
|
||||
"the": "the",
|
||||
"a": { "one": "a", "vowel": "an" }
|
||||
},
|
||||
"prompt": {
|
||||
"yes": "y",
|
||||
"no": "n",
|
||||
"all": "a",
|
||||
"skip": "s",
|
||||
"quit": "q"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### `core.*` - Semantic Intents
|
||||
|
||||
Intents encode meaning and behavior:
|
||||
|
||||
```json
|
||||
{
|
||||
"core": {
|
||||
"edit": {
|
||||
"_meta": {
|
||||
"type": "action",
|
||||
"verb": "common.verb.edit",
|
||||
"dangerous": false
|
||||
},
|
||||
"question": "Should I {{.Verb}} {{.Subject}}?",
|
||||
"confirm": "{{.Verb | title}} {{.Subject}}?",
|
||||
"success": "{{.Subject | title}} {{.Verb | past}}",
|
||||
"failure": "Failed to {{.Verb}} {{.Subject}}"
|
||||
},
|
||||
"delete": {
|
||||
"_meta": {
|
||||
"type": "action",
|
||||
"verb": "common.verb.delete",
|
||||
"dangerous": true,
|
||||
"default": "no"
|
||||
},
|
||||
"question": "Delete {{.Subject}}? This cannot be undone.",
|
||||
"confirm": "Really delete {{.Subject}}?",
|
||||
"success": "{{.Subject | title}} deleted",
|
||||
"failure": "Failed to delete {{.Subject}}"
|
||||
},
|
||||
"save": {
|
||||
"_meta": {
|
||||
"type": "action",
|
||||
"verb": "common.verb.save",
|
||||
"supports": ["all", "skip"]
|
||||
},
|
||||
"question": "Save {{.Subject}}?",
|
||||
"success": "{{.Subject | title}} saved"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Transmute Function
|
||||
|
||||
`Transmute()` combines intent metadata with input to produce contextually correct output:
|
||||
|
||||
```go
|
||||
// Signature
|
||||
func Transmute(intent string, data map[string]any) TransmuteResult
|
||||
|
||||
// TransmuteResult provides multiple output forms
|
||||
type TransmuteResult struct {
|
||||
Question string // "Delete the file?"
|
||||
Confirm string // "Really delete the file?"
|
||||
Success string // "File deleted"
|
||||
Failure string // "Failed to delete the file"
|
||||
Meta IntentMeta // Dangerous, default, supports, etc.
|
||||
}
|
||||
|
||||
// Usage
|
||||
result := i18n.Transmute("core.delete", map[string]any{
|
||||
"Subject": "/path/to/file.txt",
|
||||
})
|
||||
|
||||
if result.Meta.Dangerous {
|
||||
// Show warning styling
|
||||
}
|
||||
fmt.Println(result.Question) // "Delete /path/to/file.txt? This cannot be undone."
|
||||
```
|
||||
|
||||
## Template Functions
|
||||
|
||||
Available in translation templates:
|
||||
|
||||
| Function | Description | Example |
|
||||
|----------|-------------|---------|
|
||||
| `title` | Title case | `{{.Name \| title}}` → "Hello World" |
|
||||
| `lower` | Lower case | `{{.Name \| lower}}` → "hello world" |
|
||||
| `upper` | Upper case | `{{.Name \| upper}}` → "HELLO WORLD" |
|
||||
| `past` | Past tense verb | `{{.Verb \| past}}` → "edited" |
|
||||
| `plural` | Pluralize noun | `{{.Noun \| plural .Count}}` → "files" |
|
||||
| `article` | Add article | `{{.Noun \| article}}` → "a file" |
|
||||
| `quote` | Wrap in quotes | `{{.Path \| quote}}` → `"/path/to/file"` |
|
||||
|
||||
## Subject Helper
|
||||
|
||||
`Subject()` creates a typed subject with metadata:
|
||||
|
||||
```go
|
||||
// Simple subject
|
||||
i18n.Subject("file", "/path/to/file.txt")
|
||||
|
||||
// With count (for plurality)
|
||||
i18n.Subject("commit", commits, i18n.Count(len(commits)))
|
||||
|
||||
// With gender (for languages that need it)
|
||||
i18n.Subject("user", userName, i18n.Gender("female"))
|
||||
```
|
||||
|
||||
## CLI Integration Details
|
||||
|
||||
### cli.Confirm()
|
||||
|
||||
```go
|
||||
func Confirm(intent string, subject Subject, opts ...ConfirmOption) bool
|
||||
|
||||
// Options
|
||||
cli.DefaultYes() // Default to yes instead of no
|
||||
cli.DefaultNo() // Explicit default no
|
||||
cli.Required() // No default, must choose
|
||||
cli.Timeout(30*time.Second) // Auto-select default after timeout
|
||||
```
|
||||
|
||||
### cli.Question()
|
||||
|
||||
```go
|
||||
func Question(intent string, subject Subject, opts ...QuestionOption) string
|
||||
|
||||
// Options
|
||||
cli.Options{"all", "skip"} // Extra options beyond y/n
|
||||
cli.Default("yes") // Which option is default
|
||||
cli.Validate(func(s string) bool) // Custom validation
|
||||
```
|
||||
|
||||
### cli.Choose()
|
||||
|
||||
```go
|
||||
func Choose[T any](intent string, items []T, opts ...ChooseOption) T
|
||||
|
||||
// Options
|
||||
cli.Display(func(T) string) // How to display each item
|
||||
cli.Filter() // Enable fuzzy filtering
|
||||
cli.Multi() // Allow multiple selection
|
||||
```
|
||||
|
||||
## Implementation Plan
|
||||
|
||||
### Phase 1: Foundation
|
||||
1. Add `_meta` parsing to JSON loader
|
||||
2. Implement `Transmute()` with basic templates
|
||||
3. Add template functions (title, lower, past, etc.)
|
||||
4. Add `Subject()` helper
|
||||
|
||||
### Phase 2: CLI Integration
|
||||
1. Implement `cli.Confirm()` using intents
|
||||
2. Implement `cli.Question()` with options
|
||||
3. Implement `cli.Choose()` for lists
|
||||
4. Localize prompt characters [y/N]
|
||||
|
||||
### Phase 3: Grammar Engine
|
||||
1. Verb conjugation (past tense, etc.)
|
||||
2. Noun plurality with irregular forms
|
||||
3. Article selection (a/an, gender)
|
||||
4. Language-specific rules
|
||||
|
||||
### Phase 4: Extended Languages
|
||||
1. Gender agreement (French, German, etc.)
|
||||
2. Formality levels (Japanese, Korean, etc.)
|
||||
3. Right-to-left support
|
||||
4. Plural forms beyond one/other (Russian, Arabic, etc.)
|
||||
|
||||
## Example: Full Flow
|
||||
|
||||
```go
|
||||
// In cmd/dev/dev_commit.go
|
||||
path := "/Users/dev/project"
|
||||
files := []string{"main.go", "config.yaml"}
|
||||
|
||||
// Old way (hardcoded English, manual prompt handling)
|
||||
fmt.Printf("Commit %d files in %s? [y/N] ", len(files), path)
|
||||
var response string
|
||||
fmt.Scanln(&response)
|
||||
if response != "y" && response != "Y" {
|
||||
return
|
||||
}
|
||||
|
||||
// New way (semantic, localized, integrated)
|
||||
subject := i18n.Subject("file", path, i18n.Count(len(files)))
|
||||
if !cli.Confirm("core.commit", subject) {
|
||||
return
|
||||
}
|
||||
|
||||
// For German user, displays:
|
||||
// "2 Dateien in /Users/dev/project committen? [j/N]"
|
||||
// (note: "j" for "ja" instead of "y" for "yes")
|
||||
```
|
||||
|
||||
## JSON Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"common": {
|
||||
"description": "Reusable translation fragments",
|
||||
"type": "object"
|
||||
},
|
||||
"core": {
|
||||
"description": "Semantic intents with metadata",
|
||||
"type": "object",
|
||||
"additionalProperties": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"_meta": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"type": { "enum": ["action", "question", "info"] },
|
||||
"verb": { "type": "string" },
|
||||
"dangerous": { "type": "boolean" },
|
||||
"default": { "enum": ["yes", "no"] },
|
||||
"supports": { "type": "array", "items": { "type": "string" } }
|
||||
}
|
||||
},
|
||||
"question": { "type": "string" },
|
||||
"confirm": { "type": "string" },
|
||||
"success": { "type": "string" },
|
||||
"failure": { "type": "string" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Open Questions
|
||||
|
||||
1. **Verb conjugation library** - Use existing Go library or build custom?
|
||||
2. **Gender detection** - How to infer gender for subjects in gendered languages?
|
||||
3. **Fallback behavior** - What happens when intent metadata is missing?
|
||||
4. **Caching** - Should compiled templates be cached?
|
||||
5. **Validation** - How to validate intent definitions at build time?
|
||||
Loading…
Add table
Reference in a new issue