/ember-intl

Localization library for any Ember Application or Addon

Primary LanguageJavaScriptMIT LicenseMIT

ember-intl

npm Version Ember Version CI npm Ember Observer Score

Notable Features

  • 💵 Locale-aware numbers. Formatting of currencies, decimals, and percentages
  • 📅 Locale-aware dates and times formatting
  • 🕑 Locale-aware display of relative time. i.e, "in 1 day", "2 years ago", etc.
  • 💬 ICU Message Syntax. Pluralization and formatted segments (numbers, datetime, etc.)
  • 🌐 Support for 150+ languages
  • 🕵🏻 Translation linting (detects missing translations & translation argument mismatches)
  • 📜 Built largely on standards. ICU message syntax & Native Intl API
  • ⚡ Extensive Ember Service API and template helpers for formatting and translating
  • 🎉 Advanced addon support to provide translations to the host app

Documentation

5.x

4.x (legacy)

Migrating from 4.x to 5.x

Notable Changes

  • Improved the internals for loading translations on boot
  • Polyfills have been remove and no longer bundle pluralization rules as they're available natively via the Intl.PluralRules API

Breaking Changes

  • Node 8 support dropped
  • Improved ICU-spec compliance, special characters are now escaped via a single quote ' instead of a slash \
  • Intl.RelativeTime polyfill has been replaced with the native API which behaves entirely different than the previous older spec implementation (read about in the Migration Document)
  • intl.lookup() API will no longer return missing translation warnings
  • Removes shortNumber formatting in favor of now supported native implementation using the "notation" property i.e.,
this.intl.formatNumber(1000, {
  notation: "compact" ,
  compactDisplay: "short"
}); // -> 1k

All of this will result in smaller bundles, faster build times, and less work done on app boot.

When you're ready to upgrade, head over to the Migration Document to read more in detail about what changed.

TypeScript Support

Support for TypeScript has been added in v5.5.0. If you have any custom types, you can remove them now. When injecting the intl service, type it like so:

import Component from '@glimmer/component';
import type IntlService from 'ember-intl/services/intl';

export default class ExampleComponent extends Component {
  @service declare intl: IntlService;
}

You may encounter seemingly unrelated type errors when updating to ember-intl@^5.5.0, like:

./node_modules/@types/es-abstract/GetIntrinsic.d.ts(555,58): error TS2339: Property 'flat' does not exist on type 'any[]'.
./node_modules/@types/es-abstract/GetIntrinsic.d.ts(556,61): error TS2339: Property 'flatMap' does not exist on type 'any[]'.
./node_modules/@types/es-abstract/GetIntrinsic.d.ts(597,57): error TS2339: Property 'flat' does not exist on type 'any[]'.
./node_modules/@types/es-abstract/GetIntrinsic.d.ts(598,60): error TS2339: Property 'flatMap' does not exist on type 'any[]'.
./node_modules/@types/es-abstract/GetIntrinsic.d.ts(949,47): error TS2339: Property 'fromEntries' does not exist on type 'ObjectConstructor'.
./node_modules/@types/es-abstract/GetIntrinsic.d.ts(965,48): error TS2339: Property 'allSettled' does not exist on type 'PromiseConstructor'.
./node_modules/@types/es-abstract/GetIntrinsic.d.ts(1064,64): error TS2339: Property 'matchAll' does not exist on type 'String'.
./node_modules/@types/es-abstract/GetIntrinsic.d.ts(1082,65): error TS2339: Property 'trimStart' does not exist on type 'String'.
./node_modules/@types/es-abstract/GetIntrinsic.d.ts(1084,63): error TS2339: Property 'trimEnd' does not exist on type 'String'.
./node_modules/@types/es-abstract/GetIntrinsic.d.ts(1115,63): error TS2339: Property 'matchAll' does not exist on type 'String'.
./node_modules/@types/es-abstract/GetIntrinsic.d.ts(1133,64): error TS2339: Property 'trimStart' does not exist on type 'String'.
./node_modules/@types/es-abstract/GetIntrinsic.d.ts(1135,62): error TS2339: Property 'trimEnd' does not exist on type 'String'.
./node_modules/@types/es-abstract/GetIntrinsic.d.ts(1145,94): error TS2339: Property 'description' does not exist on type 'Symbol'.
./node_modules/@types/es-abstract/GetIntrinsic.d.ts(1153,44): error TS2339: Property 'matchAll' does not exist on type 'SymbolConstructor'.
./node_modules/@types/es-abstract/GetIntrinsic.d.ts(1163,93): error TS2339: Property 'description' does not exist on type 'Symbol'.

You can fix these by adding ES2020 to your compilerOptions.lib or setting the compilerOptions.target to ES2020 in tsconfig.json. See #1426 for more details.

Migrating from ember-i18n

There's an ember-i18n-to-intl-migrator tool that is used to convert your translations files and application code to ember-intl.

If you have any questions or issues, please open in ember-i18n-to-intl-migrator/issues