localized

localized provides immutable UTF-8 text keyed by canonical BCP 47 language tags. Exact lookup, language matching, and application fallback are separate operations. The package does not provide catalogs, formatting, pluralization, translation loading, language detection, or global locale policy.

Install

go get github.com/faustbrian/go-localized

Go 1.26.6 or later is required.

Five-minute tour

englishTag, err := locale.Parse("en")
if err != nil {
    return err
}
finnishTag, _ := locale.Parse("fi")
canadianEnglish, _ := locale.Parse("en-CA")
swedishTag, _ := locale.Parse("sv")

text, err := localized.NewText(
    localized.Entry{Locale: englishTag, Text: "Hello"},
    localized.Entry{Locale: finnishTag, Text: "Hei"},
)
if err != nil {
    return err
}

english, present := text.Get(englishTag) // exact only
_ = english
_ = present

matched, err := localizedmatch.Best(text,
    localizedmatch.Preference{Locale: canadianEnglish, Weight: 1},
)
if err != nil {
    return err
}

plan, err := localizedmatch.NewFallbackPlan(
    []locale.Tag{swedishTag, englishTag}, nil, 4,
)
if err != nil {
    return err
}
fallback := plan.Resolve(text)

overlay, _ := localized.TextFromMap(map[string]string{"en": "Hi"})
merged, err := text.Merge(overlay, localized.RightWins)
if err != nil {
    return err
}

canonicalJSON, err := localized.EncodeJSON(merged)
_ = matched
_ = fallback
_ = canonicalJSON

For SQL and pgx, use postgres.NewText(value) and postgres.JSONBCodec(). See the quickstart for complete construction, fallback, merge, JSON, and PostgreSQL examples.

Guarantees

• caller maps, entry slices, rows, iterators, and encoded bytes do not alias retained state;
• locale keys use canonical international/locale.Tag identity;
• missing and present-empty are distinguished by every lookup result;
• iteration and canonical encoding are lexically deterministic;
• fallback never inserts an invented translation;
• parser, locale, text, matching, fallback, merge, and telemetry work is bounded;
• production code has no mutable globals, unsafe, cgo, go:linkname, cache, goroutine, registry refresh, or process-global locale;
• package-generated errors and events never include localized content.

Documentation

Start at the documentation index. The normative behavior is in semantics, the complete public surface in the API reference, and operational constraints in security and performance. Observable standards interpretations are governed by the specification decision register.

Development

make check runs the complete local gate stack through the pinned go-library-tools CLI. Hosted workflows mirror these commands, but local development does not depend on a remote branch or CI run. PostgreSQL-backed checks require an explicitly supplied disposable database:

POSTGRES_URL='postgres://postgres:postgres@127.0.0.1:5432/localized?sslmode=disable' \
  make check

The PostgreSQL version matrix is a CI operation. It uses isolated ephemeral containers and verifies PostgreSQL 14 through 18 without using ambient services.

License

MIT. See LICENSE, NOTICE, and THIRD_PARTY_NOTICES.md.