localization

Documentation

Overview

Package localization is the high-level localization layer for gofluent. It formats messages across an ordered chain of locale Bundles with fallback: the first bundle that resolves a message wins. Bundles are built eagerly and formatting is synchronous. It mirrors fluent.js Localization combined with @fluent/sequence's mapBundleSync.

This package depends only on the core fluent package and the standard library. Bundles inherit the core's default CLDR formatters; override them (or set other options) through Config.BundleOptions.

Index

• type Config
• type Localization
  • func New(bundles []*fluent.Bundle) *Localization
  • func NewFromLocales(cfg Config) (*Localization, []error)
  • func (l *Localization) Bundles() []*fluent.Bundle
  • func (l *Localization) FormatMessage(id string, args map[string]any) (Message, []error)
  • func (l *Localization) FormatValue(id string, args map[string]any) (string, []error)
• type Message
• type NotFoundError
  • func (e *NotFoundError) Error() string
• type ResourceLoader
  • func FSLoader(fsys fs.FS, pathPattern string) ResourceLoader

Types

type Config

type Config struct {
	// Requested is the user's locale preference list, in priority order.
	Requested []string
	// Available is the set of locales the application ships.
	Available []string
	// Default is appended as the last-resort locale. langneg.Lookup requires
	// it to be non-empty.
	Default string
	// Strategy selects the negotiation algorithm. The zero value is
	// langneg.Filtering.
	Strategy langneg.Strategy
	// Resources lists the resource ids loaded into every bundle.
	Resources []string
	// Loader resolves a (locale, resource id) pair to FTL source.
	Loader ResourceLoader
	// BundleOptions are forwarded to every fluent.NewBundle call, e.g. to
	// override the default formatters per bundle.
	BundleOptions []fluent.Option
}

Config configures NewFromLocales.

type Localization

type Localization struct {
	// contains filtered or unexported fields
}

Localization holds an ordered slice of bundles, highest-priority locale first. Formatting walks the chain and returns the first resolution.

func New

func New(bundles []*fluent.Bundle) *Localization

New builds a Localization from already-constructed bundles, in priority order (highest-priority locale first). Callers retain ownership of the input slice.

func NewFromLocales

func NewFromLocales(cfg Config) (*Localization, []error)

NewFromLocales negotiates the supported locales out of cfg.Requested and cfg.Available against cfg.Default, then builds one Bundle per negotiated locale by loading every cfg.Resources id through cfg.Loader. Bundles are built in negotiated (priority) order.

Loader and AddResource errors are collected and returned but are non-fatal: a failing resource is skipped so the rest of the chain still works, and a bundle is created for each negotiated locale regardless. A negotiation error is fatal: the Localization is nil.

func (*Localization) Bundles

func (l *Localization) Bundles() []*fluent.Bundle

Bundles returns the localization's bundles in priority order. The returned slice is a copy.

func (*Localization) FormatMessage

func (l *Localization) FormatMessage(id string, args map[string]any) (Message, []error)

FormatMessage resolves a whole message (value plus all attributes) from the first bundle in the chain that defines it. The value is "" when the message has only attributes. On a total miss the value is the id and the errors contain a single *NotFoundError.

func (*Localization) FormatValue

func (l *Localization) FormatValue(id string, args map[string]any) (string, []error)

FormatValue formats the message (or attribute) identified by id, walking the bundle chain in priority order. id may be "msg" or "msg.attr". A bundle is skipped when its message has no value (value form) or lacks the requested attribute (attribute form). Resolver errors encountered in the winning bundle are returned. On a total miss the id is returned unchanged together with a single *NotFoundError.

This mirrors fluent.js Localization.formatValue layered over the fluent-dom dotted attribute syntax.

type Message

type Message struct {
	Value      string
	Attributes map[string]string
}

Message is a fully formatted message: its value and all of its attributes.

type NotFoundError

type NotFoundError struct {
	ID string
}

NotFoundError reports that an id could not be resolved in any bundle.

func (*NotFoundError) Error

func (e *NotFoundError) Error() string

type ResourceLoader

type ResourceLoader func(locale, resourceID string) (string, error)

ResourceLoader loads the FTL source for a (locale, resourceID) pair. It returns an error if the resource cannot be found or read; missing resources are tolerated (the resulting bundle simply lacks those messages).

func FSLoader

func FSLoader(fsys fs.FS, pathPattern string) ResourceLoader

FSLoader returns a ResourceLoader that reads FTL sources from an fs.FS (for example an embed.FS or a testing/fstest.MapFS).

pathPattern is a template containing the placeholders "{locale}" and "{resource}", which are substituted with the requested locale and resource id to form the path passed to fs.ReadFile. For example:

FSLoader(fsys, "{locale}/{resource}.ftl")

loads "de/main.ftl" for locale "de" and resource "main". Any error from fs.ReadFile (such as a missing file) is propagated to the caller, which treats it as a non-fatal, skipped resource.