Skip to content

Latest commit

 

History

History
140 lines (110 loc) · 5.73 KB

intro.md

File metadata and controls

140 lines (110 loc) · 5.73 KB

The Unicode MessageFormat Standard 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 Functions
  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.

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

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

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 default functions.

Updates to this specification will not remove any options or option values defined for default functions.

Important

Functions that are not marked Draft are Stable and subject to the provisions of this stability policy.

Functions or options marked as Draft are not stable. Their name, operands, and options/option values, and other requirements might change or be removed before being declared Stable in a future release.

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 identifiers which are reserved identifiers.

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 default functions. 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.