diff --git a/exploration/registry-xml/README.md b/exploration/registry-xml/README.md new file mode 100644 index 000000000..75b049041 --- /dev/null +++ b/exploration/registry-xml/README.md @@ -0,0 +1,183 @@ +# MessageFormat 2.0 Registry + +Implementations and tooling can greatly benefit from a +structured definition of formatting and matching functions available to messages at runtime. + +> [!IMPORTANT] +> This definition was initially developed to be a part of the MessageFormat 2.0 specification, +> but has been left out in preference of less structural definitions of message functions +> and an expectation that real-world experience with tooling will be able to inform +> later considerations to return to this topic. + +## Goals + +The registry provides a description of MessageFormat 2 functions, +in order to support the following goals and use-cases: + +- Validate semantic properties of messages. For example: + - Type-check values passed into functions. + - Validate that matching functions are only called in selectors. + - Validate that formatting functions are only called in placeholders. + - Verify the exhaustiveness of variant keys given a selector. +- Support the localization roundtrip. For example: + - Generate variant keys for a given locale during XLIFF extraction. +- Improve the authoring experience. For example: + - Forbid edits to certain function options (e.g. currency options). + - Autocomplete function and option names. + - Display on-hover tooltips for function signatures with documentation. + - Display/edit known message metadata. + - Restrict input in GUI by providing a dropdown with all viable option values. + +## Conformance and Use + +Implementations are not required to provide a machine-readable registry +nor to read or interpret the registry data model in order to be conformant. + +The MessageFormat 2.0 Registry was created to describe +the core set of formatting and selection _functions_, +including _operands_, _options_, and _option_ values. +This is the minimum set of functionality needed for conformance. +By using the same names and values, _messages_ can be used interchangeably +by different implementations, +regardless of programming language or runtime environment. +This ensures that developers do not have to relearn core MessageFormat syntax +and functionality when moving between platforms +and that translators do not need to know about the runtime environment for most +selection or formatting operations. + +The registry provides a machine-readable description of _functions_ +suitable for tools, such as those used in translation automation, so that +variant expansion and information about available _options_ and their effects +are available in the translation ecosystem. +To that end, implementations are strongly encouraged to provide appropriately +tailored versions of the registry for consumption by tools +(even if not included in software distributions) +and to encourage any add-on or plug-in functionality to provide +a registry to support localization tooling. + +## Registry Data Model + +MessageFormat 2 functions can be invoked in two contexts: + +- inside placeholders, to produce a part of the message's formatted output; + for example, a raw value of `|1.5|` may be formatted to `1,5` in a language which uses commas as decimal separators, +- inside selectors, to contribute to selecting the appropriate variant among all given variants. + +A single _function name_ may be used in both contexts, +regardless of whether it's implemented as one or multiple functions. + +A _signature_ defines one particular set of at most one argument and any number of named options +that can be used together in a single call to the function. +`` corresponds to a function call inside a placeholder inside translatable text. +`` corresponds to a function call inside a selector. + +A signature may define the positional argument of the function with the `` element. +If the `` element is not present, the function is defined as a nullary function. +A signature may also define one or more `