Skip to content

Latest commit

 

History

History
151 lines (118 loc) · 6.4 KB

intro.md

File metadata and controls

151 lines (118 loc) · 6.4 KB
Raw

MessageFormat 2.0 Specification

Table of Contents

  1. Introduction
    1. Conformance
    2. Terminology and Conventions
    3. Stability Policy
  2. Syntax
    1. message.abnf
  3. Formatting
  4. Errors
  5. Default Function Registry
  6. u: Namespace
  7. Interchange data model
  8. Appendices
    1. Security Considerations
    2. Acknowledgements

Introduction

One of the challenges in adapting software to work for users with different languages and cultures is the need for dynamic messages. Whenever a user interface needs to present data as part of a larger string, that data needs to be formatted (and the message may need to be altered) to make it culturally accepted and grammatically correct.

For example, if your US English (en-US) interface has a message like:

Your item had 1,023 views on April 3, 2023

You want the translated message to be appropriately formatted into French:

Votre article a eu 1 023 vues le 3 avril 2023

Or Japanese:

あなたのアイテムは 2023 年 4 月 3 日に 1,023 回閲覧されました。

This specification defines the data model, syntax, processing, and conformance requirements for the next generation of dynamic messages. It is intended for adoption by programming languages and APIs. This will enable the integration of existing internationalization APIs (such as the date and number formats shown above), grammatical matching (such as plurals or genders), as well as user-defined formats and message selectors.

The document is the successor to ICU MessageFormat, henceforth called ICU MessageFormat 1.0.

Conformance

Everything in this specification is normative except for: sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

Terminology and Conventions

A term looks like this when it is defined in this specification.

A reference to a term looks like this.

Examples are non-normative and styled like this.

Important

Text marked "Important" like this are normative.

Note

Notes are non-normative.

Stability Policy

Important

The provisions of the stability policy are not in effect until the conclusion of the technical preview and adoption of this specification.

Updates to this specification will not make any valid message invalid.

Updates to this specification will not remove any syntax provided in this version.

Updates to this specification will not specify an error for any message that previously did not specify an error.

Updates to this specification will not specify the use of a fallback value for any message that previously did not specify a fallback value.

Updates to this specification will not change the syntactical meaning of any syntax defined in this specification.

Updates to this specification will not remove any functions defined in the default function registry.

Updates to this specification will not remove any options or option values defined in the default function registry.

Note

The foregoing policies are not a guarantee that the results of formatting will never change. Even when this specification or its implementation do not change, the function handlers for date formatting, number formatting and so on can change their results over time or behave differently due to local runtime differences in implementation or changes to locale data (such as due to the release of new CLDR versions).

Updates to this specification will only reserve, define, or require function identifiers and function option identifiers which satisfy either of the following two requirements:

  • Includes no namespace, and has a name consisting of characters in the ranges a-z, A-Z, and 0-9, and the characters U+002E FULL STOP ., U+002D HYPHEN-MINUS -, and U+005F LOW LINE _.
  • Uses a namespace consisting of a single character in the ranges a-z and A-Z.

All other identifiers in these categories are reserved for the use of implementations or users.

Note

Users defining custom identifiers SHOULD include at least one character outside these ranges to ensure that they will be compatible with future versions of this specification. They SHOULD also use the namespace feature to avoid collisions with other implementations.

Future versions of this specification will not introduce changes to the data model that would result in a data model representation based on this version being invalid.

For example, existing interfaces or fields will not be removed.

Important

This stability policy allows any of the following, non-exhaustive list, of changes in future versions of this specification:

  • Future versions may define new syntax and structures that would not be supported by this version of the specification.
  • Future versions may add additional structure or meaning to existing syntax.
  • Future versions may define new keywords.
  • Future versions may make previously invalid messages valid.
  • Future versions may define additional functions in the default registry or may reserve the names of functions for the purposes of interoperability.
  • Future versions may define additional options to existing functions.
  • Future versions may define additional option values for existing options.
  • Future versions may deprecate (but not remove) keywords, functions, options, or option values.
  • Future versions of this specification may introduce changes to the data model that would result in future data model representations not being valid for implementations of this version of the data model.
    • For example, a future version could introduce a new keyword, whose data model representation would be a new interface that is not recognized by this version's data model.