localization

Documentation

Overview

Package localization is the high-level, synchronous localization layer for gofluent. It formats messages across an ordered chain of locale Bundles with fallback, mirroring the behavior of fluent.js Localization combined with @fluent/sequence's mapBundleSync (first bundle that has the message wins).

Unlike fluent.js, this layer is synchronous: Go's use case and the ergonomics of the language make the async-iterator machinery unnecessary. Bundles are built eagerly.

This package depends only on the core fluent package and the standard library; it does not import fluentx. Callers wire pluggable formatters by passing fluent.BundleOption values through to the bundle builders.

Index

• type L10nID
• type Localization
  • func New(bundles []*fluent.Bundle) *Localization
  • func NewFromLocales(requested, available []string, defaultLocale string, resourceIDs []string, ...) (*Localization, []error)
  • func NewFromLocalesStrategy(requested, available []string, defaultLocale string, strategy langneg.Strategy, ...) (*Localization, []error)
  • func (l *Localization) Bundles() []*fluent.Bundle
  • func (l *Localization) FormatMessage(id string, args map[string]any) (value string, attributes map[string]string, found bool, errs []error)
  • func (l *Localization) FormatValue(id string, args map[string]any) (string, []error)
  • func (l *Localization) FormatValues(ids []L10nID) ([]string, []error)
• type NotFoundError
  • func (e *NotFoundError) Error() string
• type ResourceLoader
  • func FSLoader(fsys fs.FS, pathPattern string) ResourceLoader

Types

type L10nID

type L10nID struct {
	ID   string
	Args map[string]any
}

L10nID is a single batch request: a message id (optionally dotted with an attribute, "msg.attr") plus its formatting arguments.

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). The slice is copied.

func NewFromLocales

func NewFromLocales(
	requested, available []string,
	defaultLocale string,
	resourceIDs []string,
	loader ResourceLoader,
	bundleOpts ...fluent.BundleOption,
) (*Localization, []error)

NewFromLocales is the higher-level constructor. It negotiates the supported locales out of requested/available against defaultLocale (Filtering strategy), then builds one Bundle per negotiated locale by loading every resourceID through loader and AddResource-ing it. Bundles are returned in negotiated (priority) order.

bundleOpts are forwarded to every fluent.NewBundle call, so callers can wire fluentx (or any other) formatters per bundle.

Loader and parse errors are collected and returned but are non-fatal: a failing resource is skipped so the rest of the chain still works. A bundle is always created for each negotiated locale even if some of its resources fail to load.

func NewFromLocalesStrategy

func NewFromLocalesStrategy(
	requested, available []string,
	defaultLocale string,
	strategy langneg.Strategy,
	resourceIDs []string,
	loader ResourceLoader,
	bundleOpts ...fluent.BundleOption,
) (*Localization, []error)

NewFromLocalesStrategy is NewFromLocales with an explicit negotiation strategy.

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) (value string, attributes map[string]string, found bool, errs []error)

FormatMessage resolves a whole message (value plus all attributes) from the first bundle in the chain that defines it. found reports whether any bundle had the message; when false value is the id and attributes is nil. value is "" when the message has only attributes and no value. Mirrors fluent.js messageFromBundle layered over formatWithFallback.

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". The first bundle whose message — and, for the dotted form, whose attribute — resolves wins. Resolver errors encountered in the winning bundle are returned. On a total miss the id is returned unchanged together with a single not-found error.

This mirrors fluent.js Localization.formatValue (via formatValues) layered over the fluent-dom dotted attribute syntax.

func (*Localization) FormatValues

func (l *Localization) FormatValues(ids []L10nID) ([]string, []error)

FormatValues formats a batch of ids, each with its own args. The returned slice is positional (one entry per input). Errors from all entries are concatenated. Mirrors fluent.js Localization.formatValues.

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

Error implements the error interface.

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.