gui/docs/framework/i18n.md

I18n Service

The I18n service (pkg/i18n) provides internationalization and localization support with automatic language detection and template-based translations.

Features

• JSON-based locale files
• Embedded locale bundles
• Automatic language detection from environment
• Template variable interpolation
• BCP 47 language tag support

Basic Usage

import "github.com/Snider/Core/pkg/i18n"

// Create service (defaults to English)
i18n, err := i18n.New()
if err != nil {
    log.Fatal(err)
}

Setting Language

// Set language using BCP 47 tag
err := i18n.SetLanguage("fr")
err := i18n.SetLanguage("en-US")
err := i18n.SetLanguage("zh-Hans")

Translating Messages

// Simple translation
msg := i18n.Translate("welcome_message")

// With template data
msg := i18n.Translate("greeting", map[string]string{
    "Name": "John",
})
// Template: "Hello, {{.Name}}!"
// Result: "Hello, John!"

Available Languages

// Get list of available language codes
langs := i18n.AvailableLanguages()
// Returns: ["en", "es", "fr", "de", ...]

Get All Messages

// Get all translations for a language
messages, err := i18n.GetAllMessages("en")
for key, value := range messages {
    fmt.Printf("%s: %s\n", key, value)
}

Locale File Format

Locale files are JSON stored in locales/ directory:

// locales/en.json
{
    "welcome": "Welcome to the application",
    "greeting": "Hello, {{.Name}}!",
    "items_count": {
        "one": "{{.Count}} item",
        "other": "{{.Count}} items"
    }
}

Adding New Languages

1. Create a new JSON file in pkg/i18n/locales/:

   locales/es.json
   

2. Add translations:

   {
       "welcome": "Bienvenido a la aplicación",
       "greeting": "¡Hola, {{.Name}}!"
   }
   

3. The service automatically loads embedded locales at startup.

Language Detection

The service can detect system language from the LANG environment variable:

// Automatic detection happens internally
// LANG=fr_FR.UTF-8 -> French
// LANG=de_DE.UTF-8 -> German

Frontend Usage (TypeScript)

import {
    SetLanguage,
    Translate,
    AvailableLanguages,
    GetAllMessages
} from '@bindings/i18n/service';

// Set language
await SetLanguage("fr");

// Translate
const welcome = await Translate("welcome_message");

// Get available languages for a selector
const languages = await AvailableLanguages();

// Load all messages for client-side caching
const messages = await GetAllMessages("en");