1 | # ember-intl
|
2 |
|
3 | [![npm Version][npm-badge]][npm]
|
4 | ![Ember Version][ember-version]
|
5 | ![CI](https://github.com/ember-intl/ember-intl/workflows/CI/badge.svg)
|
6 | [![npm](https://img.shields.io/npm/dm/ember-intl.svg)](https://www.npmjs.com/package/ember-intl)
|
7 | [![Ember Observer Score](http://emberobserver.com/badges/ember-intl.svg)](http://emberobserver.com/addons/ember-intl)
|
8 |
|
9 | ## Notable Features
|
10 |
|
11 | * 💵 Locale-aware numbers. Formatting of currencies, decimals, and percentages
|
12 | * 📅 Locale-aware dates and times formatting
|
13 | * 🕑 Locale-aware display of relative time. i.e, `"in 1 day"`, `"2 years ago"`, etc.
|
14 | * 💬 ICU Message Syntax. Pluralization and formatted segments (numbers, datetime, etc.)
|
15 | * 🌐 Support for 150+ languages
|
16 | * 🕵🏻 Translation linting (detects missing translations & translation argument mismatches)
|
17 | * 📜 Built largely on standards. [ICU message syntax][ICU] & [Native Intl API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl)
|
18 | * ⚡ Extensive Ember Service API and template helpers for formatting and translating
|
19 | * 🎉 [Advanced addon support](https://ember-intl.github.io/ember-intl/docs/advanced/addon-support) to provide translations to the host app
|
20 |
|
21 | ## Documentation
|
22 |
|
23 | [5.x](https://ember-intl.github.io/ember-intl/versions/master/docs/quickstart)
|
24 |
|
25 | [4.x (legacy)](https://ember-intl.github.io/ember-intl/versions/v4.4.0/docs/quickstart)
|
26 |
|
27 | ## Migrating from 4.x to 5.x
|
28 | ### Notable Changes
|
29 |
|
30 | * Improved the internals for loading translations on boot
|
31 | * Polyfills have been remove and no longer bundle pluralization rules as they're available natively via the `Intl.PluralRules` API
|
32 |
|
33 | ### Breaking Changes
|
34 |
|
35 | * Node 8 support dropped
|
36 | * Improved ICU-spec compliance, special characters are now escaped via a single quote `'` instead of a slash `\`
|
37 | * `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](https://ember-intl.github.io/ember-intl/docs/guide/migration-4-0-to-5-0))
|
38 | * `intl.lookup()` API will no longer return missing translation warnings
|
39 | * Removes `shortNumber` formatting in favor of now supported native implementation using the `"notation"` property i.e.,
|
40 | ```js
|
41 | this.intl.formatNumber(1000, {
|
42 | notation: "compact" ,
|
43 | compactDisplay: "short"
|
44 | }); // -> 1k
|
45 | ```
|
46 |
|
47 | All of this will result in smaller bundles, faster build times, and less work done on app boot.
|
48 |
|
49 | When you're ready to upgrade, head over to the [Migration Document](https://ember-intl.github.io/ember-intl/docs/guide/migration-4-0-to-5-0) to read more in detail about what changed.
|
50 |
|
51 | ### TypeScript Support
|
52 |
|
53 | Support for TypeScript has been added in `v5.5.0`. If you have any custom types,
|
54 | you can remove them now. When injecting the `intl` service, type it like so:
|
55 |
|
56 | ```ts
|
57 | import Component from '@glimmer/component';
|
58 | import type IntlService from 'ember-intl/services/intl';
|
59 |
|
60 | export default class ExampleComponent extends Component {
|
61 | @service intl!: IntlService;
|
62 | }
|
63 | ```
|
64 |
|
65 | You may encounter seemingly unrelated type errors when updating to
|
66 | `ember-intl@^5.5.0`, like:
|
67 |
|
68 | ```
|
69 | ./node_modules/@types/es-abstract/GetIntrinsic.d.ts(555,58): error TS2339: Property 'flat' does not exist on type 'any[]'.
|
70 | ./node_modules/@types/es-abstract/GetIntrinsic.d.ts(556,61): error TS2339: Property 'flatMap' does not exist on type 'any[]'.
|
71 | ./node_modules/@types/es-abstract/GetIntrinsic.d.ts(597,57): error TS2339: Property 'flat' does not exist on type 'any[]'.
|
72 | ./node_modules/@types/es-abstract/GetIntrinsic.d.ts(598,60): error TS2339: Property 'flatMap' does not exist on type 'any[]'.
|
73 | ./node_modules/@types/es-abstract/GetIntrinsic.d.ts(949,47): error TS2339: Property 'fromEntries' does not exist on type 'ObjectConstructor'.
|
74 | ./node_modules/@types/es-abstract/GetIntrinsic.d.ts(965,48): error TS2339: Property 'allSettled' does not exist on type 'PromiseConstructor'.
|
75 | ./node_modules/@types/es-abstract/GetIntrinsic.d.ts(1064,64): error TS2339: Property 'matchAll' does not exist on type 'String'.
|
76 | ./node_modules/@types/es-abstract/GetIntrinsic.d.ts(1082,65): error TS2339: Property 'trimStart' does not exist on type 'String'.
|
77 | ./node_modules/@types/es-abstract/GetIntrinsic.d.ts(1084,63): error TS2339: Property 'trimEnd' does not exist on type 'String'.
|
78 | ./node_modules/@types/es-abstract/GetIntrinsic.d.ts(1115,63): error TS2339: Property 'matchAll' does not exist on type 'String'.
|
79 | ./node_modules/@types/es-abstract/GetIntrinsic.d.ts(1133,64): error TS2339: Property 'trimStart' does not exist on type 'String'.
|
80 | ./node_modules/@types/es-abstract/GetIntrinsic.d.ts(1135,62): error TS2339: Property 'trimEnd' does not exist on type 'String'.
|
81 | ./node_modules/@types/es-abstract/GetIntrinsic.d.ts(1145,94): error TS2339: Property 'description' does not exist on type 'Symbol'.
|
82 | ./node_modules/@types/es-abstract/GetIntrinsic.d.ts(1153,44): error TS2339: Property 'matchAll' does not exist on type 'SymbolConstructor'.
|
83 | ./node_modules/@types/es-abstract/GetIntrinsic.d.ts(1163,93): error TS2339: Property 'description' does not exist on type 'Symbol'.
|
84 | ```
|
85 |
|
86 | You can fix these by adding `ES2020` to your `compilerOptions.lib` or setting
|
87 | the `compilerOptions.target` to `ES2020` in `tsconfig.json`.
|
88 | See [#1426](https://github.com/ember-intl/ember-intl/issues/1426) for more details.
|
89 |
|
90 | ## Migrating from ember-i18n
|
91 |
|
92 | There's an [ember-i18n-to-intl-migrator tool](https://github.com/DockYard/ember-i18n-to-intl-migrator) that is used to convert your translations files and application code to ember-intl.
|
93 |
|
94 | If you have any questions or issues, please open in [ember-i18n-to-intl-migrator/issues](https://github.com/DockYard/ember-i18n-to-intl-migrator/issues)
|
95 |
|
96 | [npm]: https://www.npmjs.org/package/ember-intl
|
97 | [npm-badge]: https://img.shields.io/npm/v/ember-intl.svg?style=flat-square
|
98 | [ember-version]: https://img.shields.io/badge/Ember-2.12%2B-brightgreen.svg
|
99 | [ICU]: https://formatjs.io/docs/core-concepts/icu-syntax
|