i18n

i18n - Custom Internationalization Library

Custom-built internationalization system for matcha email client. Zero external i18n dependencies - everything implemented from scratch.

Table of Contents

• Architecture Overview
• Directory Structure
• Core Components
  • Translation Manager
  • Bundle System
  • Localizer
  • Plural Rules Engine
  • Template System
  • Language Registry
• Data Flow
• Translation File Format
• Plural Forms
• Caching Strategy
• Language Detection
• Adding/Editing Languages

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                      Application Layer                      │
│              (TUI components call t(), tn(), tpl())         │
└──────────────────────────┬──────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────┐
│                    Global Manager                           │
│  • Singleton instance                                       │
│  • Current language state                                   │
│  • Localizer instances                                      │
└──────────────────────────┬──────────────────────────────────┘
                           │
         ┌─────────────────┼─────────────────┐
         │                 │                 │
┌────────▼────────┐ ┌─────▼──────┐ ┌───────▼────────┐
│     Bundle      │ │  Localizer │ │     Cache      │
│  All messages   │ │  Per-lang  │ │  Translations  │
│  All locales    │ │  instance  │ │  Rendered text │
└────────┬────────┘ └─────┬──────┘ └────────────────┘
         │                │
         │         ┌──────▼──────────┐
         │         │   Pluralizer    │
         │         │  Plural rules   │
         │         └─────────────────┘
         │
┌────────▼────────────────────────────────────────────────────┐
│                   Translation Files                         │
│            locales/en.json, locales/uk.json, ...            │
└─────────────────────────────────────────────────────────────┘

Directory Structure

i18n/
├── manager.go           # Global singleton manager
├── bundle.go            # Translation bundle storage
├── locale.go            # Locale representation
├── message.go           # Message structure (with plural forms)
├── localizer.go         # Per-language translation engine
├── loader.go            # Load & embed translation files
├── parser.go            # JSON parser for translation files
├── plural_rules.go      # Plural rule functions for all languages
├── pluralizer.go        # Plural form selection logic
├── template.go          # Simple {var} template engine
├── interpolator.go      # Variable interpolation in strings
├── cache.go             # In-memory translation cache
├── fallback.go          # Fallback chain (uk → en)
├── detector.go          # Auto-detect user language
├── registry.go          # Available languages registry
├── formatter.go         # Number formatting per locale
├── date_formatter.go    # Date/time formatting per locale
├── context.go           # Context keys for locale passing
├── errors.go            # Error types
├── init.go              # Package initialization
├── embed.go             # Embed translation files in binary
├── languages/           # Language-specific implementations
│   ├── base.go          # Base language interface
│   ├── en.go            # English locale registration
│   ├── uk.go            # Ukrainian locale registration
│   ├── es.go            # Spanish locale registration
│   └── ...              # Other languages
└── locales/             # Translation JSON files
    ├── en.json          # English translations (base)
    ├── uk.json          # Ukrainian translations
    └── ...              # Other language files

Core Components

Translation Manager

File: manager.go

Global singleton that coordinates all i18n operations. Provides three main translation functions:

• T(key) - Simple translation lookup
• Tn(key, count, data) - Translation with pluralization
• Tpl(key, data) - Translation with template variables

// Usage in TUI components
import "github.com/floatpane/matcha/i18n"

func render() string {
    title := i18n.GetManager().T("composer.title")
    count := i18n.GetManager().Tn("inbox.unread", 5, map[string]interface{}{
        "count": 5,
    })
    return title + " - " + count
}

Maintains:

• Current active language
• Bundle with all loaded translations
• Localizer instances per language
• Translation cache

Bundle System

File: bundle.go

Central storage for all translation messages across all languages. Thread-safe with RWMutex.

type Bundle struct {
    defaultLang string
    messages    map[string]MessageMap  // lang → message ID → Message
    locales     map[string]*Locale     // lang → Locale info
    mu          sync.RWMutex
}

Responsibilities:

• Store translations for all languages
• Retrieve messages by language + key
• Register locale definitions
• List available languages

Localizer

File: localizer.go

Per-language translation engine. Each active language gets one localizer instance.

type Localizer struct {
    lang    string
    bundle  *Bundle
    locale  *Locale
    cache   *Cache
}

Core methods:

• Localize(messageID) - Basic lookup
• LocalizePlural(messageID, count, data) - With plural rules
• LocalizeTemplate(messageID, data) - With variable substitution

Handles:

• Message lookup with fallback
• Plural form selection
• Template interpolation
• Result caching

Plural Rules Engine

Files: plural_rules.go, pluralizer.go

Implements CLDR plural rules for all supported languages.

type PluralForm int

const (
    Zero PluralForm = iota  // 0 items
    One                     // 1 item
    Two                     // 2 items (Arabic, Welsh)
    Few                     // 2-4 items (Slavic languages)
    Many                    // 5+ items (Slavic languages)
    Other                   // Default/fallback
)

Each language has specific rules:

English/Spanish: Simple (one/other)

func EnglishPlural(n int) PluralForm {
    if n == 1 {
        return One
    }
    return Other
}

Ukrainian/Russian: Complex (one/few/many)

func UkrainianPlural(n int) PluralForm {
    mod10 := n % 10
    mod100 := n % 100
    
    if mod10 == 1 && mod100 != 11 {
        return One     // 1, 21, 31, 41...
    }
    if mod10 >= 2 && mod10 <= 4 && (mod100 < 12 || mod100 > 14) {
        return Few     // 2-4, 22-24, 32-34...
    }
    return Many        // 0, 5-20, 25-30...
}

Arabic: Very complex (zero/one/two/few/many/other)

Template System

Files: template.go, interpolator.go

Simple variable substitution using {variable} syntax.

template := "Update available: {latest} (current: {current})"
data := map[string]interface{}{
    "latest": "1.5.0",
    "current": "1.4.0",
}
result := Interpolate(template, data)
// → "Update available: 1.5.0 (current: 1.4.0)"

Design philosophy: Keep simple - no complex logic, just variable replacement. Complex formatting done in Go code before passing to templates.

Language Registry

File: registry.go

Global registry of all available languages. Languages self-register on init.

// In languages/uk.go
func init() {
    i18n.RegisterLanguage(&i18n.Locale{
        Code:       "uk",
        Name:       "Ukrainian",
        NativeName: "Українська",
        Direction:  "ltr",
        PluralFunc: i18n.UkrainianPlural,
    })
}

Registry provides:

• GetLanguage(code) - Lookup locale by code
• AvailableLanguages() - List all registered locales
• LanguageCodes() - List all language codes

Data Flow

Translation Lookup Flow

1. TUI calls t("composer.title")
              ↓
2. Manager.T() → GetLocalizer(currentLang)
              ↓
3. Localizer checks cache
   • Cache hit? → return cached value
   • Cache miss? → continue
              ↓
4. Bundle.GetMessage(lang, "composer.title")
   • Found? → return Message
   • Not found? → try fallback chain (uk → en)
              ↓
5. Return message.One (singular form)
              ↓
6. Cache result for future lookups
              ↓
7. Return translated string to TUI

Pluralization Flow

1. TUI calls tn("inbox.unread", 5, {"count": 5})
              ↓
2. Manager.Tn() → GetLocalizer(currentLang)
              ↓
3. Get Message from bundle
              ↓
4. Call locale.PluralFunc(5)
   • English: 5 → Other
   • Ukrainian: 5 → Many
   • Arabic: 5 → Few
              ↓
5. Select appropriate form from Message:
   • message.One (n=1)
   • message.Few (n=2-4 in Ukrainian)
   • message.Many (n=5+ in Ukrainian)
   • message.Other (fallback)
              ↓
6. Interpolate {count} → "5"
              ↓
7. Return "5 листів" (Ukrainian) or "5 emails" (English)

Translation File Format

Location: locales/*.json

Structure:

{
  "language": "uk",
  "messages": {
    "common": {
      "yes": "Так",
      "no": "Ні",
      "save": "Зберегти"
    },
    "composer": {
      "title": "Написати новий лист",
      "send": "Надіслати",
      "from": "Від"
    },
    "inbox": {
      "unread": {
        "one": "{count} непрочитаний лист",
        "few": "{count} непрочитані листи",
        "other": "{count} непрочитаних листів"
      }
    }
  }
}

Nested structure: Dot notation for keys (composer.title, inbox.unread)

Plural objects: When value is object with one/few/many/other, it's treated as plural form.

Plural Forms

Languages use different plural categories:

Caching Strategy

File: cache.go

Simple in-memory string cache with RWMutex for thread safety.

Cache key format: {lang}:{messageID}:{count}:{hash(data)}

Why cache?

• Translation lookup involves: map lookups, plural calculation, interpolation
• Typical UI has ~100 translated strings
• Redrawing UI on every keypress = wasted CPU
• Cache hit = instant string return

Cache invalidation: Cache cleared when language changes via SetLanguage().

No size limit: Translation cache is small (~KB for entire UI) and only grows to unique message combinations actually used.

Language Detection

File: detector.go

Detection priority:

1. Config file: language = "uk" in ~/.config/matcha/config.toml
2. Environment: LANG, LC_ALL, LC_MESSAGES
3. System locale: OS-specific detection
4. Default: Falls back to "en"

func DetectLanguage(cfg *config.Config) string {
    // 1. Check config
    if cfg.Language != "" && isValidLanguage(cfg.Language) {
        return cfg.Language
    }
    
    // 2. Check environment
    if lang := detectFromEnv(); lang != "" {
        return lang
    }
    
    // 3. Check system
    if lang := detectFromSystem(); lang != "" {
        return lang
    }
    
    // 4. Default
    return "en"
}

Normalizes language codes: en_US.UTF-8 → en, uk_UA → uk

Adding/Editing Languages

Adding a New Language

1. Create translation file:

cd i18n/locales
cp en.json xx.json  # Replace 'xx' with language code (ISO 639-1)

2. Update language code:

{
  "language": "xx",
  "messages": { ... }
}

3. Translate all strings:

• Keep JSON structure identical to en.json
• Translate all message values
• Preserve placeholders: {count}, {latest}, {current}
• Don't translate technical terms: S/MIME, PGP, IMAP, SMTP
• Don't translate commands: matcha update

4. Handle plural forms:

Check plural rules for your language at CLDR Plural Rules.

Add plural forms as needed:

"hours_ago": {
  "one": "{count} hour ago",
  "other": "{count} hours ago"
}

For complex plurals (Ukrainian, Arabic, Polish):

"address_count": {
  "one": "{count} адреса",
  "few": "{count} адреси",
  "other": "{count} адрес"
}

5. Register language (if not already in languages/):

Create languages/xx.go:

package languages

import "github.com/floatpane/matcha/i18n"

func init() {
    i18n.RegisterLanguage(&i18n.Locale{
        Code:       "xx",
        Name:       "YourLanguage",
        NativeName: "YourLanguageInNativeScript",
        Direction:  "ltr",  // or "rtl" for Arabic, Hebrew, etc.
        PluralFunc: i18n.YourLanguagePlural,
    })
}

If plural function doesn't exist in plural_rules.go, add it:

// In plural_rules.go
func YourLanguagePlural(n int) PluralForm {
    // Implement CLDR rules for your language
    if n == 1 {
        return One
    }
    return Other
}

6. Test:

go build
# Edit config: language = "xx"
./matcha

Verify:

• All UI elements translated
• Plural forms work (test with 0, 1, 2, 5, 21 items)
• Variables interpolate correctly
• No English leaks through

Editing Existing Translations

1. Open translation file:

vi i18n/locales/uk.json

2. Find key using dot notation:

Translation keys follow UI structure:

• composer.* - Email composer
• inbox.* - Inbox view
• settings_general.* - General settings
• common.* - Shared elements

3. Update translation:

{
  "composer": {
    "title": "Old translation"  // Change this
  }
}

4. Rebuild and test:

go build
./matcha

Language changes apply instantly (no restart needed).

Translation Guidelines

Do translate:

• All visible UI text
• Button labels
• Menu items
• Help text
• Tips
• Error messages shown to user
• Status messages

Don't translate:

• Backend error logs
• Debug messages
• Protocol names (IMAP, SMTP, S/MIME, PGP)
• File paths (~/.config/matcha/)
• Environment variables ($EDITOR)
• Commands (matcha update)
• Technical identifiers

Variable placeholders:

Always keep variables unchanged:

// ✅ Correct
"update_available": "Доступне оновлення: {latest} (встановлено: {current})"

// ❌ Wrong - renamed variable
"update_available": "Доступне оновлення: {останній} (встановлено: {поточний})"

Testing Checklist

• All screens display in target language
• Test plural forms with different counts (0, 1, 2, 5, 21)
• Variables interpolate correctly
• No untranslated English text (except technical terms)
• Text fits in UI (not truncated)
• Special characters render properly
• RTL languages display correctly (Arabic, Hebrew)
• Date/time formats work
• Help text makes sense in context

Contributing Translations

1. Fork repository
2. Add/edit translation file in i18n/locales/
3. Test thoroughly with checklist above
4. Submit pull request with:
   • Translation file
   • Screenshots of translated UI
   • Note about plural form testing
   • List any technical challenges

Translation quality > completeness. Better to have 80% high-quality translation than 100% machine-translated text.

For more details on using translations in code, see: Documentation.