i18n

package
v0.12.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 26, 2026 License: MPL-2.0 Imports: 7 Imported by: 0

Documentation

Overview

Package i18n provides dependency-free typed message catalog helpers.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Format 

func Format(message string, vars map[string]string) string

Format replaces literal {name} placeholders with values.

func FormatDate added in v0.12.0 

func FormatDate(locale string, value time.Time, style DateStyle) string

FormatDate formats a date using the supported deterministic style.

func FormatNumber added in v0.12.0 

func FormatNumber(locale string, value float64, options NumberFormatOptions) string

FormatNumber formats a number with deterministic locale separators. It is a bounded helper, not a CLDR replacement.

func FormatPlural added in v0.12.0 

func FormatPlural(locale string, count int, forms PluralForms, vars map[string]string) string

FormatPlural selects a plural form, injects {count}, and applies Format.

func FormatTime added in v0.12.0 

func FormatTime(locale string, value time.Time, style TimeStyle) string

FormatTime formats a time using the supported deterministic style.

Types

type Bundle 

type Bundle[K comparable] struct {
	DefaultLocale string
	Catalogs      map[string]Catalog[K]
}

Bundle stores catalogs by locale code.

func NewBundle 

func NewBundle[K comparable](defaultLocale string, catalogs map[string]Catalog[K]) Bundle[K]

NewBundle creates a catalog bundle with defensive copies.

func (Bundle[K]) Catalog 

func (bundle Bundle[K]) Catalog(locale string) (Catalog[K], bool)

Catalog returns the requested locale catalog or the default catalog.

func (Bundle[K]) Check added in v0.12.0 

func (bundle Bundle[K]) Check(required []MessageReference[K]) BundleReport[K]

Check returns a deterministic completeness report for the required message references. Missing keys, unused keys, and missing default catalogs are reported without panicking so app tests can decide the failure policy.

func (Bundle[K]) Template added in v0.12.0 

func (bundle Bundle[K]) Template(locale string, required []MessageReference[K]) CatalogTemplate[K]

Template returns a deterministic starter catalog for one locale. Existing values are used only when that exact locale is already present.

type BundleReport added in v0.12.0 

type BundleReport[K comparable] struct {
	DefaultLocale string                `json:"defaultLocale,omitempty"`
	Required      []MessageReference[K] `json:"required,omitempty"`
	Catalogs      []CatalogReport[K]    `json:"catalogs,omitempty"`
}

BundleReport summarizes catalog completeness across locales.

func (BundleReport[K]) Error added in v0.12.0 

func (report BundleReport[K]) Error() string

Error renders the report as indented JSON for app-owned tests.

func (BundleReport[K]) OK added in v0.12.0 

func (report BundleReport[K]) OK() bool

OK reports whether the bundle has no missing catalogs, missing keys, or unused keys for the checked required references.

type Catalog 

type Catalog[K comparable] struct {
	Locale   string
	Messages map[K]string
}

Catalog maps typed keys to localized messages for one locale.

func NewCatalog 

func NewCatalog[K comparable](locale string, messages map[K]string) Catalog[K]

NewCatalog creates a catalog with a defensive message copy.

func (Catalog[K]) Format 

func (catalog Catalog[K]) Format(key K, vars map[string]string) (string, bool)

Format replaces {name} placeholders in the keyed message. Missing variables are left intact so callers can detect incomplete data in tests.

func (Catalog[K]) Message 

func (catalog Catalog[K]) Message(key K) (string, bool)

Message returns the localized message for key.

func (Catalog[K]) MissingKeys 

func (catalog Catalog[K]) MissingKeys(keys []K) []K

MissingKeys reports typed keys absent from the catalog.

func (Catalog[K]) Must 

func (catalog Catalog[K]) Must(key K) string

Must returns the localized message for key or panics when the key is missing. It is intended for build-time data functions and tests where missing keys should fail fast.

func (Catalog[K]) MustFormat 

func (catalog Catalog[K]) MustFormat(key K, vars map[string]string) string

MustFormat is the panic-on-missing-key variant of Format.

func (Catalog[K]) Template added in v0.12.0 

func (catalog Catalog[K]) Template(required []MessageReference[K]) CatalogTemplate[K]

Template returns a deterministic starter catalog for the required keys. Any existing catalog values are copied into the template entries.

type CatalogReport added in v0.12.0 

type CatalogReport[K comparable] struct {
	Locale         string                `json:"locale,omitempty"`
	MissingCatalog bool                  `json:"missingCatalog,omitempty"`
	Missing        []MessageReference[K] `json:"missing,omitempty"`
	Unused         []K                   `json:"unused,omitempty"`
}

CatalogReport is the deterministic completeness report for one locale.

type CatalogTemplate added in v0.12.0 

type CatalogTemplate[K comparable] struct {
	Locale  string                    `json:"locale"`
	Entries []CatalogTemplateEntry[K] `json:"entries"`
}

CatalogTemplate is a deterministic locale-specific starter catalog.

type CatalogTemplateEntry added in v0.12.0 

type CatalogTemplateEntry[K comparable] struct {
	Key    K      `json:"key"`
	Value  string `json:"value"`
	Source string `json:"source,omitempty"`
	Line   int    `json:"line,omitempty"`
	Column int    `json:"column,omitempty"`
}

CatalogTemplateEntry is one deterministic entry in a catalog template.

type DateStyle added in v0.12.0 

type DateStyle string

DateStyle selects a deterministic date format. 

const (
	DateShort  DateStyle = "short"
	DateMedium DateStyle = "medium"
)

type MessageReference added in v0.12.0 

type MessageReference[K comparable] struct {
	Key    K      `json:"key"`
	Source string `json:"source,omitempty"`
	Line   int    `json:"line,omitempty"`
	Column int    `json:"column,omitempty"`
}

MessageReference records one expected message key and, optionally, where it was declared or used. Apps can keep these references beside build helpers or generated extraction output and check catalogs in ordinary Go tests.

func Key added in v0.12.0 

func Key[K comparable](key K) MessageReference[K]

Key records an expected message key without source metadata.

func Ref added in v0.12.0 

func Ref[K comparable](key K, source string, line int, column int) MessageReference[K]

Ref records an expected message key with source metadata.

type NumberFormatOptions added in v0.12.0 

type NumberFormatOptions struct {
	MinFractionDigits int
	MaxFractionDigits int
}

NumberFormatOptions controls dependency-free number formatting.

type PluralCategory added in v0.12.0 

type PluralCategory string

PluralCategory is the bounded core plural category set. 

const (
	PluralZero  PluralCategory = "zero"
	PluralOne   PluralCategory = "one"
	PluralOther PluralCategory = "other"
)

func Cardinal added in v0.12.0 

func Cardinal(locale string, count int) PluralCategory

Cardinal returns the supported plural category for count. The root runtime intentionally keeps this bounded: East Asian locale families fall back to other, and the default family uses one for exactly +/-1.

type PluralForms added in v0.12.0 

type PluralForms struct {
	Zero  string
	One   string
	Other string
}

PluralForms holds the supported plural variants. Other is the fallback.

type TimeStyle added in v0.12.0 

type TimeStyle string

TimeStyle selects a deterministic time format. 

const (
	TimeShort  TimeStyle = "short"
	TimeMedium TimeStyle = "medium"
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.