overview.html

<emu-clause id="overview">
  <h1>Overview</h1>

  <p>
    This section contains a non-normative overview of the ECMAScript 2021 Internationalization API Specification.
  </p>

  <emu-clause id="sec-internationalization-localization-globalization">
    <h1>Internationalization, Localization, and Globalization</h1>

    <p>
      Internationalization of software means designing it such that it supports or can be easily adapted to support the needs of users speaking different languages and having different cultural expectations, and enables worldwide communication between them. Localization then is the actual adaptation to a specific language and culture. Globalization of software is commonly understood to be the combination of internationalization and localization. Globalization starts at the lowest level by using a text representation that supports all languages in the world, and using standard identifiers to identify languages, countries, time zones, and other relevant parameters. It continues with using a user interface language and data presentation that the user understands, and finally often requires product-specific adaptations to the user's language, culture, and environment.
    </p>
    <p>
      The ECMAScript 2021 Language Specification lays the foundation by using Unicode for text representation and by providing a few language-sensitive functions, but gives applications little control over the behaviour of these functions. The ECMAScript 2021 Internationalization API Specification builds on this by providing a set of customizable language-sensitive functionality. The API is useful even for applications that themselves are not internationalized, as even applications targeting only one language and one region need to properly support that one language and region. However, the API also enables applications that support multiple languages and regions, even concurrently, as may be needed in server environments.
    </p>
  </emu-clause>


  <emu-clause id="sec-api-overview">
    <h1>API Overview</h1>

    <p>
      The ECMAScript 2021 Internationalization API Specification is designed to complement the ECMAScript 2021 Language Specification by providing key language-sensitive functionality. The API can be added to an implementation of the ECMAScript 2021 Language Specification (ECMA-262 12<sup>th</sup> Edition, or successor).
    </p>
    <p>
      The ECMAScript 2021 Internationalization API Specification provides several key pieces of language-sensitive functionality that are required in most applications: String comparison (collation), number formatting, date and time formatting, pluralization rules, and case conversion. While the ECMAScript 2021 Language Specification provides functions for this basic functionality (on Array.prototype: toLocaleString; on String.prototype: localeCompare, toLocaleLowerCase, toLocaleUpperCase; on Number.prototype: toLocaleString; on Date.prototype: toLocaleString, toLocaleDateString, and toLocaleTimeString), it leaves the actual behaviour of these functions largely up to implementations to define. The ECMAScript 2021 Internationalization API Specification provides additional functionality, control over the language and over details of the behaviour to be used, and a more complete specification of required functionality.
    </p>

    <p>
      Applications can use the API in two ways:

      <ol>
        <li>
          Directly, by using the constructors Intl.Collator, Intl.NumberFormat, Intl.DateTimeFormat, or Intl.PluralRules to construct an object, specifying a list of preferred languages and options to configure the behaviour of the resulting object. The object then provides a main function (compare, select, or format), which can be called repeatedly. It also provides a resolvedOptions function, which the application can use to find out the exact configuration of the object.
        </li>
        <li>
          Indirectly, by using the functions of the ECMAScript 2021 Language Specification mentioned above. The collation and formatting functions are respecified in this specification to accept the same arguments as the Collator, NumberFormat, and DateTimeFormat constructors and produce the same results as their compare or format methods. The case conversion functions are respecified to accept a list of preferred languages.
        </li>
      </ol>
    </p>

    <p>
      The Intl object is used to package all functionality defined in the ECMAScript 2021 Internationalization API Specification to avoid name collisions.
    </p>
  </emu-clause>

  <emu-clause id="sec-implementation-dependencies">
    <h1>Implementation Dependencies</h1>

    <p>
      Due to the nature of internationalization, the API specification has to leave several details implementation dependent:

      <ul>
        <li>
          <em>The set of locales that an implementation supports with adequate localizations:</em> Linguists estimate the number of human languages to around 6000, and the more widely spoken ones have variations based on regions or other parameters. Even large locale data collections, such as the Common Locale Data Repository, cover only a subset of this large set. Implementations targeting resource-constrained devices may have to further reduce the subset.
        </li>
        <li>
          <em>The exact form of localizations such as format patterns:</em> In many cases locale-dependent conventions are not standardized, so different forms may exist side by side, or they vary over time. Different internationalization libraries may have implemented different forms, without any of them being actually wrong. In order to allow this API to be implemented on top of existing libraries, such variations have to be permitted.
        </li>
        <li>
          <em>Subsets of Unicode:</em> Some operations, such as collation, operate on strings that can include characters from the entire Unicode character set. However, both the Unicode standard and the ECMAScript standard allow implementations to limit their functionality to subsets of the Unicode character set. In addition, locale conventions typically don't specify the desired behaviour for the entire Unicode character set, but only for those characters that are relevant for the locale. While the Unicode Collation Algorithm combines a default collation order for the entire Unicode character set with the ability to tailor for local conventions, subsets and tailorings still result in differences in behaviour.
        </li>
      </ul>
    </p>

    <emu-clause id="sec-compatibility">
      <h1>Compatibility across implementations</h1>

      <p>
        ECMA 402 describes the schema of the data used by its functions. The
        data contained inside is implementation-dependent, and expected to
        change over time and vary between implementations. The variation is
        visible by programmers, and it is possible to construct programs which
        will depend on a particular output. However, this specification
        attempts to describe reasonable constraints which will allow
        well-written programs to function across implementations.
        Implementations are encouraged to continue their efforts to harmonize
        linguistic data.
      </p>
    </emu-clause>
  </emu-clause>

</emu-clause>