i18n

Example demonstrates basic translation usage with filesystem loader

package main

import (
	"fmt"
	"log"
	"os"
	"path/filepath"

	"github.com/0verkilll/i18n"
)

func main() {
	// Create temporary directory for this example
	tmpDir := setupExampleLocales()
	defer func() { _ = os.RemoveAll(tmpDir) }() //nolint:errcheck // Cleanup in test, error is non-critical

	// Create translator with filesystem loader
	translator, err := i18n.New(
		i18n.WithFileSystemLoader(tmpDir),
		i18n.WithDefaultLocale("en-US"),
	)
	if err != nil {
		_ = os.RemoveAll(tmpDir) //nolint:errcheck // Best-effort cleanup before Fatal
		log.Fatal(err)           //nolint:gocritic // Cleanup already done before Fatal
	}

	// Simple translation
	greeting := translator.Translate("greeting")
	fmt.Println(greeting)

	// Nested key translation
	title := translator.Translate("user.profile.title")
	fmt.Println(title)

}

// setupExampleLocales creates example locale files for basic translation examples.
func setupExampleLocales() string {
	tmpDir := os.TempDir() + "/i18n-example"
	_ = os.MkdirAll(tmpDir, 0o755)

	enUS := []byte(`{
		"greeting": "Hello",
		"welcome": "Welcome, %s!",
		"farewell": "Goodbye",
		"user": {
			"profile": {
				"title": "User Profile"
			}
		},
		"items_count": "You have %d items",
		"multi": "%s has %d items"
	}`)
	_ = os.WriteFile(filepath.Join(tmpDir, "en-US.json"), enUS, 0o644)

	esES := []byte(`{
		"greeting": "Hola",
		"farewell": "Adios"
	}`)
	_ = os.WriteFile(filepath.Join(tmpDir, "es-ES.json"), esES, 0o644)

	return tmpDir
}

Output:
Hello
User Profile

Example_customComponents demonstrates using custom loader and parser

package main

import (
	"fmt"
	"log"
	"os"
	"path/filepath"

	"github.com/0verkilll/i18n"
)

func main() {
	tmpDir := setupExampleLocales()
	defer func() { _ = os.RemoveAll(tmpDir) }() //nolint:errcheck // Cleanup in test, error is non-critical

	// Create custom components
	loader := i18n.NewFileSystemLoader(tmpDir)
	parser := i18n.NewJSONParser()
	resolver := i18n.NewDefaultKeyResolver()

	translator, err := i18n.New(
		i18n.WithLoader(loader),
		i18n.WithParser(parser),
		i18n.WithResolver(resolver),
		i18n.WithDefaultLocale("en-US"),
	)
	if err != nil {
		_ = os.RemoveAll(tmpDir) //nolint:errcheck // Best-effort cleanup before Fatal
		log.Fatal(err)           //nolint:gocritic // Cleanup already done before Fatal
	}

	result := translator.Translate("greeting")
	fmt.Println(result)

}

// setupExampleLocales creates example locale files for basic translation examples.
func setupExampleLocales() string {
	tmpDir := os.TempDir() + "/i18n-example"
	_ = os.MkdirAll(tmpDir, 0o755)

	enUS := []byte(`{
		"greeting": "Hello",
		"welcome": "Welcome, %s!",
		"farewell": "Goodbye",
		"user": {
			"profile": {
				"title": "User Profile"
			}
		},
		"items_count": "You have %d items",
		"multi": "%s has %d items"
	}`)
	_ = os.WriteFile(filepath.Join(tmpDir, "en-US.json"), enUS, 0o644)

	esES := []byte(`{
		"greeting": "Hola",
		"farewell": "Adios"
	}`)
	_ = os.WriteFile(filepath.Join(tmpDir, "es-ES.json"), esES, 0o644)

	return tmpDir
}

Output:
Hello

Example_embeddedFS demonstrates using embedded filesystem for translations

package main

import (
	"embed"
	"fmt"
	"log"

	"github.com/0verkilll/i18n"
)

//go:embed testdata/locales/*.json
var exampleEmbeddedLocales embed.FS

func main() {
	// Create loader with embedded filesystem
	loader := i18n.NewEmbedFSLoader(exampleEmbeddedLocales, "testdata/locales")

	translator, err := i18n.New(
		i18n.WithLoader(loader),
		i18n.WithDefaultLocale("en-US"),
	)
	if err != nil {
		log.Fatal(err) //nolint:gocritic // Cleanup already done before Fatal
	}

	// Use translations from embedded files
	greeting := translator.Translate("greeting")
	fmt.Println(greeting)

}

Output:
Hello

Example_fallbackChain demonstrates locale fallback behavior

package main

import (
	"fmt"
	"log"
	"os"
	"path/filepath"

	"github.com/0verkilll/i18n"
)

func main() {
	tmpDir := setupExampleLocalesWithFallback()
	defer func() { _ = os.RemoveAll(tmpDir) }() //nolint:errcheck // Cleanup in test, error is non-critical

	translator, err := i18n.New(
		i18n.WithFileSystemLoader(tmpDir),
		i18n.WithDefaultLocale("en-US"),
	)
	if err != nil {
		_ = os.RemoveAll(tmpDir) //nolint:errcheck // Best-effort cleanup before Fatal
		log.Fatal(err)           //nolint:gocritic // Cleanup already done before Fatal
	}

	// Switch to Mexican Spanish (has partial translations)
	translator.SetLocale("es-MX")

	// This exists in es-MX
	fmt.Println("greeting:", translator.Translate("greeting"))

	// This doesn't exist in es-MX, falls back to es-ES
	fmt.Println("farewell:", translator.Translate("farewell"))

	// This doesn't exist in es-MX or es-ES, falls back to en-US
	fmt.Println("welcome:", translator.Translate("welcome"))

}

// setupExampleLocalesWithFallback creates example locale files with partial
// translations to demonstrate fallback chain behavior.
func setupExampleLocalesWithFallback() string {
	tmpDir := os.TempDir() + "/i18n-example-fallback"
	_ = os.MkdirAll(tmpDir, 0o755)

	enUS := []byte(`{
		"greeting": "Hello",
		"welcome": "Welcome",
		"farewell": "Goodbye"
	}`)
	_ = os.WriteFile(filepath.Join(tmpDir, "en-US.json"), enUS, 0o644)

	esES := []byte(`{
		"greeting": "Hola",
		"farewell": "Adios"
	}`)
	_ = os.WriteFile(filepath.Join(tmpDir, "es-ES.json"), esES, 0o644)

	esMX := []byte(`{
		"greeting": "Hola (Mexico)"
	}`)
	_ = os.WriteFile(filepath.Join(tmpDir, "es-MX.json"), esMX, 0o644)

	return tmpDir
}

Output:
greeting: Hola (Mexico)
farewell: Adios
welcome: Welcome

Example_hasKey demonstrates checking for key existence

package main

import (
	"fmt"
	"log"
	"os"
	"path/filepath"

	"github.com/0verkilll/i18n"
)

func main() {
	tmpDir := setupExampleLocales()
	defer func() { _ = os.RemoveAll(tmpDir) }() //nolint:errcheck // Cleanup in test, error is non-critical

	translator, err := i18n.New(
		i18n.WithFileSystemLoader(tmpDir),
		i18n.WithDefaultLocale("en-US"),
	)
	if err != nil {
		_ = os.RemoveAll(tmpDir) //nolint:errcheck // Best-effort cleanup before Fatal
		log.Fatal(err)           //nolint:gocritic // Cleanup already done before Fatal
	}

	// Check simple key
	if translator.HasKey("greeting") {
		fmt.Println("greeting exists")
	}

	// Check nested key
	if translator.HasKey("user.profile.title") {
		fmt.Println("user.profile.title exists")
	}

	// Check non-existent key
	if !translator.HasKey("nonexistent") {
		fmt.Println("nonexistent does not exist")
	}

}

// setupExampleLocales creates example locale files for basic translation examples.
func setupExampleLocales() string {
	tmpDir := os.TempDir() + "/i18n-example"
	_ = os.MkdirAll(tmpDir, 0o755)

	enUS := []byte(`{
		"greeting": "Hello",
		"welcome": "Welcome, %s!",
		"farewell": "Goodbye",
		"user": {
			"profile": {
				"title": "User Profile"
			}
		},
		"items_count": "You have %d items",
		"multi": "%s has %d items"
	}`)
	_ = os.WriteFile(filepath.Join(tmpDir, "en-US.json"), enUS, 0o644)

	esES := []byte(`{
		"greeting": "Hola",
		"farewell": "Adios"
	}`)
	_ = os.WriteFile(filepath.Join(tmpDir, "es-ES.json"), esES, 0o644)

	return tmpDir
}

Output:
greeting exists
user.profile.title exists
nonexistent does not exist

Example_localeNormalization demonstrates automatic locale normalization

package main

import (
	"fmt"
	"log"
	"os"
	"path/filepath"

	"github.com/0verkilll/i18n"
)

func main() {
	tmpDir := setupExampleLocales()
	defer func() { _ = os.RemoveAll(tmpDir) }() //nolint:errcheck // Cleanup in test, error is non-critical

	translator, err := i18n.New(
		i18n.WithFileSystemLoader(tmpDir),
		i18n.WithDefaultLocale("en-US"),
	)
	if err != nil {
		_ = os.RemoveAll(tmpDir) //nolint:errcheck // Best-effort cleanup before Fatal
		log.Fatal(err)           //nolint:gocritic // Cleanup already done before Fatal
	}

	// Underscore is normalized to hyphen
	translator.SetLocale("en_US")
	fmt.Println(translator.GetLocale())

	// Encoding suffix is removed
	translator.SetLocale("es_ES.UTF-8")
	fmt.Println(translator.GetLocale())

	// POSIX locale normalized to en-US
	translator.SetLocale("POSIX")
	fmt.Println(translator.GetLocale())

}

// setupExampleLocales creates example locale files for basic translation examples.
func setupExampleLocales() string {
	tmpDir := os.TempDir() + "/i18n-example"
	_ = os.MkdirAll(tmpDir, 0o755)

	enUS := []byte(`{
		"greeting": "Hello",
		"welcome": "Welcome, %s!",
		"farewell": "Goodbye",
		"user": {
			"profile": {
				"title": "User Profile"
			}
		},
		"items_count": "You have %d items",
		"multi": "%s has %d items"
	}`)
	_ = os.WriteFile(filepath.Join(tmpDir, "en-US.json"), enUS, 0o644)

	esES := []byte(`{
		"greeting": "Hola",
		"farewell": "Adios"
	}`)
	_ = os.WriteFile(filepath.Join(tmpDir, "es-ES.json"), esES, 0o644)

	return tmpDir
}

Output:
en-US
es-ES
en-US

Example_localeSwitching demonstrates changing locales at runtime

package main

import (
	"fmt"
	"log"
	"os"
	"path/filepath"

	"github.com/0verkilll/i18n"
)

func main() {
	tmpDir := setupExampleLocales()
	defer func() { _ = os.RemoveAll(tmpDir) }() //nolint:errcheck // Cleanup in test, error is non-critical

	translator, err := i18n.New(
		i18n.WithFileSystemLoader(tmpDir),
		i18n.WithDefaultLocale("en-US"),
	)
	if err != nil {
		_ = os.RemoveAll(tmpDir) //nolint:errcheck // Best-effort cleanup before Fatal
		log.Fatal(err)           //nolint:gocritic // Cleanup already done before Fatal
	}

	// English greeting
	fmt.Println(translator.GetLocale()+":", translator.Translate("greeting"))

	// Switch to Spanish
	translator.SetLocale("es-ES")
	fmt.Println(translator.GetLocale()+":", translator.Translate("greeting"))

	// Switch back to English
	translator.SetLocale("en-US")
	fmt.Println(translator.GetLocale()+":", translator.Translate("greeting"))

}

// setupExampleLocales creates example locale files for basic translation examples.
func setupExampleLocales() string {
	tmpDir := os.TempDir() + "/i18n-example"
	_ = os.MkdirAll(tmpDir, 0o755)

	enUS := []byte(`{
		"greeting": "Hello",
		"welcome": "Welcome, %s!",
		"farewell": "Goodbye",
		"user": {
			"profile": {
				"title": "User Profile"
			}
		},
		"items_count": "You have %d items",
		"multi": "%s has %d items"
	}`)
	_ = os.WriteFile(filepath.Join(tmpDir, "en-US.json"), enUS, 0o644)

	esES := []byte(`{
		"greeting": "Hola",
		"farewell": "Adios"
	}`)
	_ = os.WriteFile(filepath.Join(tmpDir, "es-ES.json"), esES, 0o644)

	return tmpDir
}

Output:
en-US: Hello
es-ES: Hola
en-US: Hello

Example_missingKey demonstrates behavior when a translation key is not found

package main

import (
	"fmt"
	"log"
	"os"
	"path/filepath"

	"github.com/0verkilll/i18n"
)

func main() {
	tmpDir := setupExampleLocales()
	defer func() { _ = os.RemoveAll(tmpDir) }() //nolint:errcheck // Cleanup in test, error is non-critical

	translator, err := i18n.New(
		i18n.WithFileSystemLoader(tmpDir),
		i18n.WithDefaultLocale("en-US"),
	)
	if err != nil {
		_ = os.RemoveAll(tmpDir) //nolint:errcheck // Best-effort cleanup before Fatal
		log.Fatal(err)           //nolint:gocritic // Cleanup already done before Fatal
	}

	// Missing key returns the key itself
	result := translator.Translate("nonexistent.key")
	fmt.Println(result)

	// Check if key exists
	if !translator.HasKey("nonexistent.key") {
		fmt.Println("Key does not exist")
	}

}

// setupExampleLocales creates example locale files for basic translation examples.
func setupExampleLocales() string {
	tmpDir := os.TempDir() + "/i18n-example"
	_ = os.MkdirAll(tmpDir, 0o755)

	enUS := []byte(`{
		"greeting": "Hello",
		"welcome": "Welcome, %s!",
		"farewell": "Goodbye",
		"user": {
			"profile": {
				"title": "User Profile"
			}
		},
		"items_count": "You have %d items",
		"multi": "%s has %d items"
	}`)
	_ = os.WriteFile(filepath.Join(tmpDir, "en-US.json"), enUS, 0o644)

	esES := []byte(`{
		"greeting": "Hola",
		"farewell": "Adios"
	}`)
	_ = os.WriteFile(filepath.Join(tmpDir, "es-ES.json"), esES, 0o644)

	return tmpDir
}

Output:
nonexistent.key
Key does not exist

Example_registerParser demonstrates registering a custom parser for a new format.

External modules (e.g., i18n-toml, i18n-yaml) follow this pattern:

1. Implement TranslationParser
2. Call RegisterParser in init()
3. Application code activates via blank import

package main

import (
	"fmt"
	"log"

	"github.com/0verkilll/i18n"
)

func main() {
	// Define a mock TOML parser implementing TranslationParser
	parser := &exampleTOMLParser{}

	// Register it for the .toml extension
	err := i18n.RegisterParser(".toml", parser)
	if err != nil {
		log.Fatal(err)
	}

	// Verify .toml is now registered
	formats := i18n.RegisteredFormats()
	for _, f := range formats {
		if f == ".toml" {
			fmt.Println(".toml is registered")
		}
	}

	// Retrieve it back from the registry
	got, err := i18n.GetParser(".toml")
	if err != nil {
		log.Fatal(err)
	}
	if got != nil {
		fmt.Println("parser retrieved successfully")
	}

}

// exampleTOMLParser is a mock parser demonstrating the external module pattern.
// A real TOML parser would use github.com/BurntSushi/toml or similar.
// External parsers should enforce equivalent size and nesting depth limits
// (see MaxJSONSize and MaxJSONDepth) to maintain security parity.
type exampleTOMLParser struct{}

func (p *exampleTOMLParser) Parse(_ []byte) (map[string]interface{}, error) {
	return map[string]interface{}{"example": "toml-value"}, nil
}

Output:
.toml is registered
parser retrieved successfully

Example_withArguments demonstrates translation with format string arguments

package main

import (
	"fmt"
	"log"
	"os"
	"path/filepath"

	"github.com/0verkilll/i18n"
)

func main() {
	tmpDir := setupExampleLocales()
	defer func() { _ = os.RemoveAll(tmpDir) }() //nolint:errcheck // Cleanup in test, error is non-critical

	translator, err := i18n.New(
		i18n.WithFileSystemLoader(tmpDir),
		i18n.WithDefaultLocale("en-US"),
	)
	if err != nil {
		_ = os.RemoveAll(tmpDir) //nolint:errcheck // Best-effort cleanup before Fatal
		log.Fatal(err)           //nolint:gocritic // Cleanup already done before Fatal
	}

	// Translation with string argument
	welcome := translator.TranslateWithArgs("welcome", "Alice")
	fmt.Println(welcome)

	// Translation with integer argument
	count := translator.TranslateWithArgs("items_count", 5)
	fmt.Println(count)

	// Translation with multiple arguments
	message := translator.TranslateWithArgs("multi", "Bob", 3)
	fmt.Println(message)

}

// setupExampleLocales creates example locale files for basic translation examples.
func setupExampleLocales() string {
	tmpDir := os.TempDir() + "/i18n-example"
	_ = os.MkdirAll(tmpDir, 0o755)

	enUS := []byte(`{
		"greeting": "Hello",
		"welcome": "Welcome, %s!",
		"farewell": "Goodbye",
		"user": {
			"profile": {
				"title": "User Profile"
			}
		},
		"items_count": "You have %d items",
		"multi": "%s has %d items"
	}`)
	_ = os.WriteFile(filepath.Join(tmpDir, "en-US.json"), enUS, 0o644)

	esES := []byte(`{
		"greeting": "Hola",
		"farewell": "Adios"
	}`)
	_ = os.WriteFile(filepath.Join(tmpDir, "es-ES.json"), esES, 0o644)

	return tmpDir
}

Output:
Welcome, Alice!
You have 5 items
Bob has 3 items

Example_withRegisteredParser demonstrates using WithRegisteredParser to configure a Translator with a registry-resolved parser.

package main

import (
	"fmt"
	"log"
	"os"
	"path/filepath"

	"github.com/0verkilll/i18n"
)

func main() {
	tmpDir := setupExampleLocales()
	defer func() { _ = os.RemoveAll(tmpDir) }() //nolint:errcheck // Cleanup in test, error is non-critical

	// Use WithRegisteredParser to pull the built-in JSON parser from the registry
	translator, err := i18n.New(
		i18n.WithFileSystemLoader(tmpDir),
		i18n.WithRegisteredParser(".json"),
		i18n.WithDefaultLocale("en-US"),
	)
	if err != nil {
		_ = os.RemoveAll(tmpDir) //nolint:errcheck // Best-effort cleanup before Fatal
		log.Fatal(err)           //nolint:gocritic // Cleanup already done before Fatal
	}

	fmt.Println(translator.Translate("greeting"))

}

// setupExampleLocales creates example locale files for basic translation examples.
func setupExampleLocales() string {
	tmpDir := os.TempDir() + "/i18n-example"
	_ = os.MkdirAll(tmpDir, 0o755)

	enUS := []byte(`{
		"greeting": "Hello",
		"welcome": "Welcome, %s!",
		"farewell": "Goodbye",
		"user": {
			"profile": {
				"title": "User Profile"
			}
		},
		"items_count": "You have %d items",
		"multi": "%s has %d items"
	}`)
	_ = os.WriteFile(filepath.Join(tmpDir, "en-US.json"), enUS, 0o644)

	esES := []byte(`{
		"greeting": "Hola",
		"farewell": "Adios"
	}`)
	_ = os.WriteFile(filepath.Join(tmpDir, "es-ES.json"), esES, 0o644)

	return tmpDir
}

Output:
Hello