diff --git a/doc/spec.md b/doc/spec.md index 9c9ca083..d74cd1d5 100644 --- a/doc/spec.md +++ b/doc/spec.md @@ -1,5 +1,5 @@ # Angular 2 Localization library specification -Library version: 0.8.8 +Library version: 0.8.9 ## Table of contents * [1 The library structure](#1) @@ -26,6 +26,7 @@ Library version: 0.8.8 * [3.3 Third scenario: you need to translate messages, dates and numbers](#3.3) * [3.3.1 Changing locale and currency](#3.3.1) * [4 Default locale](#4) + * [4.1 Storage](#4.1) * [5 Lazy routing](#5) * [6 Validation by locales](#6) * [6.1 Validating a number](#6.1) @@ -240,10 +241,10 @@ Now you can localize a list simply. For example: #### 2.4.1 Sorting & search [LocalizationService](#7.2) has the following methods for sorting and filtering a list by locales: -* `sort` -* `sortAsync` -* `search` -* `searchAsync` +* `sort(list: Array, keyName: any, order?: string, extension?: string, options?: any): Array;` +* `sortAsync(list: Array, keyName: any, order?: string, extension?: string, options?: any): Observable>;` +* `search(s: string, list: Array, keyNames: any[], options?: any): Array;` +* `searchAsync(s: string, list: Array, keyNames: any[], options?: any): Observable;` These methods use the [Intl.Collator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Collator) object, a constructor for collators, objects that enable language sensitive string comparison. @@ -297,6 +298,7 @@ export class AppComponent { // Add a new language here. // Required: default language and expiry (No days). If the expiry is omitted, the cookie becomes a session cookie. + // Selects the current language of the browser/user if it has been added, else the default language. this.locale.definePreferredLanguage('en', 30); } @@ -376,6 +378,7 @@ this.locale.addLanguage('en'); // Add a new language here. // Required: default language, country (ISO 3166 two-letter, uppercase code) and expiry (No days). If the expiry is omitted, the cookie becomes a session cookie. +// Selects the default language and country, regardless of the browser language, to avoid inconsistencies between the language and country. this.locale.definePreferredLocale('en', 'US', 30); // Optional: default currency (ISO 4217 three-letter code). @@ -408,11 +411,30 @@ and optionally: For more information see [Intl API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl). [LocaleService](#7.1) has the following methods to define the default locale: -* `definePreferredLocale` -* `setCurrentLocale` +* `definePreferredLocale(defaultLanguage: string, defaultCountry: string, expiry?: number, script?: string, numberingSystem?: string, calendar?: string): void;` +* `setCurrentLocale(language: string, country: string, script?: string, numberingSystem?: string, calendar?: string): void;` When you invoke one of them, in addition to set the language and country, you can set the script, the numbering system and calendar. +### 4.1 Storage +By default, the default locale and eventually the currency chosen by the user are stored in cookies. When you call the following method in the [Second scenario](#3.2): +* `definePreferredLanguage(defaultLanguage: string, expiry?: number): void;` + +or, in the [Third scenario](#3.3): +* `definePreferredLocale(defaultLanguage: string, defaultCountry: string, expiry?: number, script?: string, numberingSystem?: string, calendar?: string): void;` + +you can set the cookie expiration in days - if the expiry is omitted, the cookie becomes a session cookie. + +You can also change the default storage method, enabling the `Local Storage`, before invoking the above methods: +```TypeScript +this.locale.useLocalStorage(); + +definePreferred... +``` +The `LocaleService` will try to use the Web Storage, otherwise it will attempt to use the cookie. + +*N.B. Unlike the cookie, the Local Storage doesn't expire.* + ## 5 Lazy routing If you use a `Router` in an extended application, you can create an instance of the `LocalizationService` for every asynchronously loaded component, as shown: ![LazyRouting](images/LazyRouting.png) @@ -605,11 +627,13 @@ Property | Value `numberingSystemChanged: EventEmitter;` | Output for event numbering system changed `calendarChanged: EventEmitter;` | Output for event calendar changed `enableCookie: boolean;` | Enable/disable cookie +`enableLocalStorage: boolean;` | Enable/disable Local Storage Method | Function ------ | -------- `addLanguage(language: string): void;` | Adds a new language -`definePreferredLanguage(defaultLanguage: string, expiry?: number): void;` | Defines the preferred language. Selects the current language of the browser if it has been added, else the default language +`useLocalStorage(): void;` | Sets Local Storage as default +`definePreferredLanguage(defaultLanguage: string, expiry?: number): void;` | Defines the preferred language. Selects the current language of the browser/user if it has been added, else the default language `definePreferredLocale(defaultLanguage: string, defaultCountry: string, expiry?: number, script?: string, numberingSystem?: string, calendar?: string): void;` | Defines preferred languange and country, regardless of the browser language `definePreferredCurrency(defaultCurrency: string): void;` | Defines the preferred currency `getCurrentLanguage(): string;` | Gets the current language @@ -714,8 +738,11 @@ export class MyApp { this.locale.addLanguage('en'); // Add a new language here. - // Required: default language and expiry (No days). If the expiry is omitted, the cookie becomes a session cookie. - this.locale.definePreferredLanguage('en', 30); + this.locale.useLocalStorage(); // To store the user's chosen language, prefer Local Storage. + + // Required: default language. + // Selects the current language of the browser/user if it has been added, else the default language. + this.locale.definePreferredLanguage('en'); // Initializes LocalizationService: asynchronous loading. this.localization.translationProvider('./i18n/locale-'); // Required: initializes the translation provider with the given path prefix. diff --git a/package.json b/package.json index 7dda79d5..04df4feb 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "angular2localization", - "version": "0.8.8", + "version": "0.8.9", "description": "An Angular 2 library to translate messages, dates and numbers", "main": "angular2localization.js", "jsnext:main": "esm/angular2localization.js",