mf2

README

Message Format 2

The repo implements localization by the Message Format 2 Draft of the Message Format Working Group (MFWG):

The project implements the following packages (temporary layout):

• go.expect.digital/mf2/template executes MF2 templates (WIP)
• go.expect.digital/mf2/parse parses MF2 templates (WIP)
• go.expect.digital/mf2/builder builds MF2 templates (WIP)
• CLI to extract and update localized message strings (NOT IMPLEMENTED)

Requirements

• Golang 1.22+
• IANA Time Zone database - one of:
  • the directory or uncompressed zip file named by the ZONEINFO environment variable
  • on a Unix system, the system standard installation location
  • $GOROOT/lib/time/zoneinfo.zip
  • the time/tzdata package

Features

Function registry

List of the default functions registered in the function registry. The functions support localized formatting.

Function	Signature	Option	Status
date	format	style	❌
datetime	format	dateStyle	❌
datetime	format	timeStyle	❌
datetime	format	timeZone*	❌
datetime	format	hourCycle	❌
datetime	format	dayPeriod	❌
datetime	format	weekday	❌
datetime	format	era	❌
datetime	format	year	❌
datetime	format	month	❌
datetime	format	day	❌
datetime	format	hour	❌
datetime	format	minute	❌
datetime	format	second	❌
datetime	format	fractionalSecondDigits	❌
datetime	format	timeZoneName	❌
number	format	compactDisplay	❌
number	format	currency*	❌
number	format	currencyDisplay*	❌
number	format	currencySign*	❌
number	format	notation	❌
number	format	numberingSystem	❌
number	format	signDisplay (auto, always, exceptZero, never)	✅︎
number	format	style (decimal, percent)	✅︎
number	format	style (currency, unit)	❌
number	format	unit*	❌
number	format	unitDisplay*	❌
number	format	minimumIntegerDigits	✅︎
number	format	minimumFractionDigits	✅︎
number	format	maximumFractionDigits	✅︎
number	format	minimumSignificantDigits	❌
number	format	maximumSignificantDigits	✅︎
number	match	select	✅︎
number	match	minimumIntegerDigits	✅︎
number	match	minimumFractionDigits	✅︎
number	match	maximumFractionDigits	✅︎
number	match	minimumSignificantDigits	❌
number	match	maximumSignificantDigits	✅︎
integer (number alias)	format		✅︎
integer (number alias)	match		✅︎
ordinal (number alias)			❌
plural (number alias)			❌
string			✅︎
time	format	style	❌

^* The options are not part of the default registry. MF2 WG says, "Implementations SHOULD avoid creating options that conflict with these, but are encouraged to track development of these options during Tech Preview".

Documentation

Index

• Variables

Variables

var (

	// ErrSyntax occurs when the syntax representation of a message is not well-formed.
	ErrSyntax = errors.New("syntax error")

	// ErrDataModel occur when a message is not valid due to
	// violating one of the semantic requirements on its structure.
	//
	// ErrDataModel is returned with:
	//	- ErrDuplicateDeclaration
	//	- ErrDuplicateOptionName
	//	- ErrDuplicateVariant
	//	- ErrMissingFallbackVariant
	//	- ErrMissingSelectorAnnotation
	//	- ErrVariantKeyMismatch
	ErrDataModel = errors.New("data model error")

	// ErrDuplicateDeclaration occurs when a variable is declared more than once.
	// Note that an input variable is implicitly declared when it is first used,
	// so explicitly declaring it after such use is also an error.
	ErrDuplicateDeclaration = fmt.Errorf("%w: %w", ErrDataModel, errors.New("duplicate declaration"))
	// ErrDuplicateOptionName occurs when the same identifier
	// appears on the left-hand side of more than one option in the same expression.
	ErrDuplicateOptionName = fmt.Errorf("%w: %w", ErrDataModel, errors.New("duplicate option name"))
	// ErrDuplicateVariant error occurs when the same list of keys is used
	// for more than one variant.
	ErrDuplicateVariant = fmt.Errorf("%w: %w", ErrDataModel, errors.New("duplicate variant"))
	// ErrMissingFallbackVariant occurs when the number of keys on a variant
	// does not equal the number of selectors.
	ErrMissingFallbackVariant = fmt.Errorf("%w: %w", ErrDataModel, errors.New("missing fallback variant"))
	// ErrMissingSelectorAnnotation occurs when the message
	// contains a selector that does not have an annotation,
	// or contains a variable that does not directly or indirectly reference a declaration with an annotation.
	ErrMissingSelectorAnnotation = fmt.Errorf("%w: %w", ErrDataModel, errors.New("missing selector annotation"))
	// ErrVariantKeyMismatch occurs when the number of keys on a variant
	// does not equal the number of selectors.
	ErrVariantKeyMismatch = fmt.Errorf("%w: %w", ErrDataModel, errors.New("variant key mismatch"))

	// ErrResolution occur when the runtime value of a part of a message
	// cannot be determined.
	//
	// ErrResolution is returned with:
	//	- ErrUnknownFunction
	//	- ErrUnresolvedVariable
	//	- ErrUnsupportedExpression
	//	- ErrUnsupportedStatement
	ErrResolution = errors.New("resolution error")

	// ErrUnknownFunction occurs when an expression includes
	// a reference to a function which cannot be resolved.
	ErrUnknownFunction = fmt.Errorf("%w: %w", ErrResolution, errors.New("unknown function"))
	// ErrUnresolvedVariable occurs when a variable reference cannot be resolved.
	ErrUnresolvedVariable = fmt.Errorf("%w: %w", ErrResolution, errors.New("unresolved variable"))
	// ErrUnsupportedExpression occurs when an expression uses
	// syntax reserved for future standardization,
	// or for private implementation use that is not supported by the current implementation.
	ErrUnsupportedExpression = fmt.Errorf("%w: %w", ErrResolution, errors.New("unsupported expression"))
	// ErrUnsupportedStatement occurs when a message includes a reserved statement.
	ErrUnsupportedStatement = fmt.Errorf("%w: %w", ErrResolution, errors.New("unsupported statement"))

	// ErrMessageFunction is any error that occurs when calling a message function implementation
	// or which depends on validation associated with a specific function.
	//
	// ErrMessageFunction is returned with:
	//	- ErrBadOperand
	//	- ErrBadOption
	//	- ErrBadSelector
	//	- ErrBadVariantKey
	ErrMessageFunction = errors.New("message function error")

	// ErrBadOperand is any error that occurs due to the content or format of the operand,
	// such as when the operand provided to a function during function resolution does not match one of the
	// expected implementation-defined types for that function;
	// or in which a literal operand value does not have the required format
	// and thus cannot be processed into one of the expected implementation-defined types
	// for that specific function.
	ErrBadOperand = fmt.Errorf("%w: %w", ErrMessageFunction, errors.New("bad operand"))
	// ErrBadOption is an error that occurs when there is
	// an implementation-defined error with an option or its value.
	ErrBadOption = fmt.Errorf("%w: %w", ErrMessageFunction, errors.New("bad option"))
	// ErrBadSelector occurs when a message includes a selector
	// with a resolved value which does not support selection.
	ErrBadSelector = fmt.Errorf("%w: %w", ErrMessageFunction, errors.New("bad selector"))
	// ErrBadVariantKey is an error that occurs when a variant key
	// does not match the expected implementation-defined format.
	ErrBadVariantKey = fmt.Errorf("%w: %w", ErrMessageFunction, errors.New("bad variant key"))
)

List of MF2 errors as defined in the specification.