honeymoose
/
angular-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: api doc for i18n (#29289) 

PR Close #29289
This commit is contained in:
Judy Bogart 2019-02-27 12:40:52 -08:00 committed by Jason Aden
parent eb0e29b269
commit 333bfa0ffb
4 changed files with 339 additions and 197 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
packages/common/src/i18n/format_date.ts
View File

@ -46,17 +46,18 @@ enum TranslationType {
* *
* Formats a date according to locale rules. * Formats a date according to locale rules.
* *
* Where: * @param value The date to format, as a number (milliseconds since UTC epoch)
* - `value` is a Date, a number (milliseconds since UTC epoch) or an ISO string * or an [ISO date-time string](https://www.w3.org/TR/NOTE-datetime).
* (https://www.w3.org/TR/NOTE-datetime). * @param format The date-time components to include. See `DatePipe` for details.
* - `format` indicates which date/time components to include. See {@link DatePipe} for more * @param locale A locale code for the locale format rules to use.
* details. * @param timezone The time zone. A time zone offset from GMT (such as `'+0430'`),
* - `locale` is a `string` defining the locale to use. * or a standard UTC/GMT or continental US time zone abbreviation.
* - `timezone` to be used for formatting. It understands UTC/GMT and the continental US time zone * If not specified, uses host system settings.
* abbreviations, but for general use, use a time zone offset (e.g. `'+0430'`).
* If not specified, host system settings are used.
* *
* See {@link DatePipe} for more details. * @returns The formatted date string.
*
* @see `DatePipe`
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
* *
* @publicApi * @publicApi
*/ */

53
packages/common/src/i18n/format_number.ts
View File

@ -19,7 +19,7 @@ const CURRENCY_CHAR = '¤';
const PERCENT_CHAR = '%'; const PERCENT_CHAR = '%';
/** /**
* Transforms a number to a locale string based on a style and a format * Transforms a number to a locale string based on a style and a format.
*/ */
function formatNumberToLocaleString( function formatNumberToLocaleString(
value: number, pattern: ParsedNumberFormat, locale: string, groupSymbol: NumberSymbol, value: number, pattern: ParsedNumberFormat, locale: string, groupSymbol: NumberSymbol,
@ -128,15 +128,21 @@ function formatNumberToLocaleString(
* *
* Formats a number as currency using locale rules. * Formats a number as currency using locale rules.
* *
* Use `currency` to format a number as currency. * @param value The number to format.
* @param locale A locale code for the locale format rules to use.
* @param currency A string containing the currency symbol or its name,
* such as "$" or "Canadian Dollar". Used in output string, but does not affect the operation
* of the function.
* @param currencyCode The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)
* currency code to use in the result string, such as `USD` for the US dollar and `EUR` for the euro.
* @param digitInfo Decimal representation options, specified by a string in the following format:
* `{minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}`. See `DecimalPipe` for more details.
* *
* Where: * @returns The formatted currency value.
* - `value` is a number. *
* - `locale` is a `string` defining the locale to use. * @see `formatNumber()`
* - `currency` is the string that represents the currency, it can be its symbol or its name. * @see `DecimalPipe`
* - `currencyCode` is the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code, such * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
* as `USD` for the US dollar and `EUR` for the euro.
* - `digitInfo` See {@link DecimalPipe} for more details.
* *
* @publicApi * @publicApi
*/ */
@ -163,12 +169,18 @@ export function formatCurrency(
* *
* Formats a number as a percentage according to locale rules. * Formats a number as a percentage according to locale rules.
* *
* Where: * @param value The number to format.
* - `value` is a number. * @param locale A locale code for the locale format rules to use.
* - `locale` is a `string` defining the locale to use. * @param digitInfo Decimal representation options, specified by a string in the following format:
* - `digitInfo` See {@link DecimalPipe} for more details. * `{minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}`. See `DecimalPipe` for more details.
* *
* @returns The formatted percentage value.
*
* @see `formatNumber()`
* @see `DecimalPipe`
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
* @publicApi * @publicApi
*
*/ */
export function formatPercent(value: number, locale: string, digitsInfo?: string): string { export function formatPercent(value: number, locale: string, digitsInfo?: string): string {
const format = getLocaleNumberFormat(locale, NumberFormatStyle.Percent); const format = getLocaleNumberFormat(locale, NumberFormatStyle.Percent);
@ -183,13 +195,16 @@ export function formatPercent(value: number, locale: string, digitsInfo?: string
* @ngModule CommonModule * @ngModule CommonModule
* @description * @description
* *
* Formats a number as text. Group sizing and separator and other locale-specific * Formats a number as text, with group sizing, separator, and other
* configurations are based on the locale. * parameters based on the locale.
* *
* Where: * @param value The number to format.
* - `value` is a number. * @param locale A locale code for the locale format rules to use.
* - `locale` is a `string` defining the locale to use. * @param digitInfo Decimal representation options, specified by a string in the following format:
* - `digitInfo` See {@link DecimalPipe} for more details. * `{minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}`. See `DecimalPipe` for more details.
*
* @returns The formatted text string.
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
* *
* @publicApi * @publicApi
*/ */

442
packages/common/src/i18n/locale_data_api.ts
View File

@ -11,8 +11,9 @@ import {LOCALE_DATA, LocaleDataIndex, ExtraLocaleDataIndex, CurrencyIndex} from
import {CURRENCIES_EN, CurrenciesSymbols} from './currencies'; import {CURRENCIES_EN, CurrenciesSymbols} from './currencies';
/** /**
* The different format styles that can be used to represent numbers. * Format styles that can be used to represent numbers.
* Used by the function {@link getLocaleNumberFormat}. * @see `getLocaleNumberFormat()`.
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
* *
* @publicApi * @publicApi
*/ */
@ -23,7 +24,14 @@ export enum NumberFormatStyle {
Scientific Scientific
} }
/** @publicApi */ /**
* Plurality cases used for translating plurals to different languages.
*
* @see `NgPlural`
* @see `NgPluralCase`
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* @publicApi */
export enum Plural { export enum Plural {
Zero = 0, Zero = 0,
One = 1, One = 1,
@ -34,11 +42,11 @@ export enum Plural {
} }
/** /**
* Some languages use two different forms of strings (standalone and format) depending on the * Context-dependant translation forms for strings.
* context. * Typically the standalone version is for the nominative form of the word,
* Typically the standalone version is the nominative form of the word, and the format version is in * and the format version is used for the genitive case.
* the genitive. * @see [CLDR website](http://cldr.unicode.org/translation/date-time#TOC-Stand-Alone-vs.-Format-Styles)
* See [the CLDR website](http://cldr.unicode.org/translation/date-time) for more information. * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
* *
* @publicApi * @publicApi
*/ */
@ -48,85 +56,143 @@ export enum FormStyle {
} }
/** /**
* Multiple widths are available for translations: narrow (1 character), abbreviated (3 characters), * String widths available for translations.
* wide (full length), and short (2 characters, only for days). * The specific character widths are locale-specific.
* * Examples are given for the word "Sunday" in English.
* For example the day `Sunday` will be:
* - Narrow: `S`
* - Short: `Su`
* - Abbreviated: `Sun`
* - Wide: `Sunday`
* *
* @publicApi * @publicApi
*/ */
export enum TranslationWidth { export enum TranslationWidth {
/** 1 character for `en-US`. For example: 'S' */
Narrow, Narrow,
/** 3 characters for `en-US`. For example: 'Sun' */
Abbreviated, Abbreviated,
/** Full length for `en-US`. For example: "Sunday" */
Wide, Wide,
/** 2 characters for `en-US`, For example: "Su" */
Short Short
} }
/** /**
* Multiple widths are available for formats: short (minimal amount of data), medium (small amount * String widths available for date-time formats.
* of data), long (complete amount of data), full (complete amount of data and extra information). * The specific character widths are locale-specific.
* * Examples are given for `en-US`.
* For example the date-time formats for the english locale will be:
* - `'short'`: `'M/d/yy, h:mm a'` (e.g. `6/15/15, 9:03 AM`)
* - `'medium'`: `'MMM d, y, h:mm:ss a'` (e.g. `Jun 15, 2015, 9:03:01 AM`)
* - `'long'`: `'MMMM d, y, h:mm:ss a z'` (e.g. `June 15, 2015 at 9:03:01 AM GMT+1`)
* - `'full'`: `'EEEE, MMMM d, y, h:mm:ss a zzzz'` (e.g. `Monday, June 15, 2015 at
* 9:03:01 AM GMT+01:00`)
* *
* @see `getLocaleDateFormat()`
* @see `getLocaleTimeFormat()``
* @see `getLocaleDateTimeFormat()`
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
* @publicApi * @publicApi
*/ */
export enum FormatWidth { export enum FormatWidth {
/**
* For `en-US`, 'M/d/yy, h:mm a'`
* (Example: `6/15/15, 9:03 AM`)
*/
Short, Short,
/**
* For `en-US`, `'MMM d, y, h:mm:ss a'`
* (Example: `Jun 15, 2015, 9:03:01 AM`)
*/
Medium, Medium,
/**
* For `en-US`, `'MMMM d, y, h:mm:ss a z'`
* (Example: `June 15, 2015 at 9:03:01 AM GMT+1`)
*/
Long, Long,
/**
* For `en-US`, `'EEEE, MMMM d, y, h:mm:ss a zzzz'`
* (Example: `Monday, June 15, 2015 at 9:03:01 AM GMT+01:00`)
*/
Full Full
} }
/** /**
* Number symbol that can be used to replace placeholders in number patterns. * Symbols that can be used to replace placeholders in number patterns.
* The placeholders are based on english values: * Examples are based on `en-US` values.
* *
* | Name | Example for en-US | Meaning | * @see `getLocaleNumberSymbol()`
* |------------------------|-------------------|---------------------------------------------| * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
* | decimal | 2,345`.`67 | decimal separator |
* | group | 2`,`345.67 | grouping separator, typically for thousands |
* | plusSign | `+`23 | the plus sign used with numbers |
* | minusSign | `-`23 | the minus sign used with numbers |
* | percentSign | 23.4`%` | the percent sign (out of 100) |
* | perMille | 234`‰` | the permille sign (out of 1000) |
* | exponential | 1.2`E`3 | used in computers for 1.2×10³. |
* | superscriptingExponent | 1.2`×`103 | human-readable format of exponential |
* | infinity | `∞` | used in +∞ and -∞. |
* | nan | `NaN` | "not a number". |
* | timeSeparator | 10`:`52 | symbol used between time units |
* | currencyDecimal | $2,345`.`67 | decimal separator, fallback to "decimal" |
* | currencyGroup | $2`,`345.67 | grouping separator, fallback to "group" |
* *
* @publicApi * @publicApi
*/ */
export enum NumberSymbol { export enum NumberSymbol {
/**
* Decimal separator.
* For `en-US`, the dot character.
* Example : 2,345`.`67
*/
Decimal, Decimal,
/**
* Grouping separator, typically for thousands.
* For `en-US`, the comma character.
* Example: 2`,`345.67
*/
Group, Group,
/**
* List-item separator.
* Example: "one, two, and three"
*/
List, List,
/**
* Sign for percentage (out of 100).
* Example: 23.4%
*/
PercentSign, PercentSign,
/**
* Sign for positive numbers.
* Example: +23
*/
PlusSign, PlusSign,
/**
* Sign for negative numbers.
* Example: -23
*/
MinusSign, MinusSign,
/**
* Computer notation for exponential value (n times a power of 10).
* Example: 1.2E3
*/
Exponential, Exponential,
/**
* Human-readable format of exponential.
* Example: 1.2x103
*/
SuperscriptingExponent, SuperscriptingExponent,
/**
* Sign for permille (out of 1000).
* Example: 23.4‰
*/
PerMille, PerMille,
/**
* Infinity, can be used with plus and minus.
* Example: ∞, +∞, -∞
*/
Infinity, Infinity,
/**
* Not a number.
* Example: NaN
*/
NaN, NaN,
/**
* Symbol used between time units.
* Example: 10:52
*/
TimeSeparator, TimeSeparator,
/**
* Decimal separator for currency values (fallback to `Decimal`).
* Example: $2,345.67
*/
CurrencyDecimal, CurrencyDecimal,
/**
* Group separator for currency values (fallback to `Group`).
* Example: $2,345.67
*/
CurrencyGroup CurrencyGroup
} }
/** /**
* The value for each day of the week, based on the en-US locale * The value for each day of the week, based on the `en-US` locale
* *
* @publicApi * @publicApi
*/ */
@ -141,7 +207,11 @@ export enum WeekDay {
} }
/** /**
* The locale id for the chosen locale (e.g `en-GB`). * Retrieves the locale ID from the currently loaded locale.
* The loaded locale could be, for example, a global one rather than a regional one.
* @param locale A locale code, such as `fr-FR`.
* @returns The locale code. For example, `fr`.
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
* *
* @publicApi * @publicApi
*/ */
@ -150,7 +220,13 @@ export function getLocaleId(locale: string): string {
} }
/** /**
* Periods of the day (e.g. `[AM, PM]` for en-US). * Retrieves day period strings for the given locale.
*
* @param locale A locale code for the locale format rules to use.
* @param formStyle The required grammatical form.
* @param width The required character width.
* @returns An array of localized period strings. For example, `[AM, PM]` for `en-US`.
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
* *
* @publicApi * @publicApi
*/ */
@ -165,7 +241,14 @@ export function getLocaleDayPeriods(
} }
/** /**
* Days of the week for the Gregorian calendar (e.g. `[Sunday, Monday, ... Saturday]` for en-US). * Retrieves days of the week for the given locale, using the Gregorian calendar.
*
* @param locale A locale code for the locale format rules to use.
* @param formStyle The required grammatical form.
* @param width The required character width.
* @returns An array of localized name strings.
* For example,`[Sunday, Monday, ... Saturday]` for `en-US`.
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
* *
* @publicApi * @publicApi
*/ */
@ -179,7 +262,14 @@ export function getLocaleDayNames(
} }
/** /**
* Months of the year for the Gregorian calendar (e.g. `[January, February, ...]` for en-US). * Retrieves months of the year for the given locale, using the Gregorian calendar.
*
* @param locale A locale code for the locale format rules to use.
* @param formStyle The required grammatical form.
* @param width The required character width.
* @returns An array of localized name strings.
* For example, `[January, February, ...]` for `en-US`.
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
* *
* @publicApi * @publicApi
*/ */
@ -193,7 +283,14 @@ export function getLocaleMonthNames(
} }
/** /**
* Eras for the Gregorian calendar (e.g. AD/BC). * Retrieves Gregorian-calendar eras for the given locale.
* @param locale A locale code for the locale format rules to use.
* @param formStyle The required grammatical form.
* @param width The required character width.
* @returns An array of localized era strings.
* For example, `[AD, BC]` for `en-US`.
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
* *
* @publicApi * @publicApi
*/ */
@ -204,8 +301,13 @@ export function getLocaleEraNames(locale: string, width: TranslationWidth): [str
} }
/** /**
* First day of the week for this locale, based on english days (Sunday = 0, Monday = 1, ...). * Retrieves the first day of the week for the given locale.
* For example in french the value would be 1 because the first day of the week is Monday. *
* @param locale A locale code for the locale format rules to use.
* @returns A day index number, using the 0-based week-day index for `en-US`
* (Sunday = 0, Monday = 1, ...).
* For example, for `fr-FR`, returns 1 to indicate that the first day is Monday.
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
* *
* @publicApi * @publicApi
*/ */
@ -215,9 +317,11 @@ export function getLocaleFirstDayOfWeek(locale: string): WeekDay {
} }
/** /**
* Range of days in the week that represent the week-end for this locale, based on english days * Range of week days that are considered the week-end for the given locale.
* (Sunday = 0, Monday = 1, ...). *
* For example in english the value would be [6,0] for Saturday to Sunday. * @param locale A locale code for the locale format rules to use.
* @returns The range of day values, `[startDay, endDay]`.
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
* *
* @publicApi * @publicApi
*/ */
@ -227,27 +331,13 @@ export function getLocaleWeekEndRange(locale: string): [WeekDay, WeekDay] {
} }
/** /**
* Date format that depends on the locale. * Retrieves a localized date-value formating string.
* *
* There are four basic date formats: * @param locale A locale code for the locale format rules to use.
* - `full` should contain long-weekday (EEEE), year (y), long-month (MMMM), day (d). * @param width The format type.
* * @returns The localized formating string.
* For example, English uses `EEEE, MMMM d, y`, corresponding to a date like * @see `FormatWidth`
* "Tuesday, September 14, 1999". * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* - `long` should contain year, long-month, day.
*
* For example, `MMMM d, y`, corresponding to a date like "September 14, 1999".
*
* - `medium` should contain year, abbreviated-month (MMM), day.
*
* For example, `MMM d, y`, corresponding to a date like "Sep 14, 1999".
* For languages that do not use abbreviated months, use the numeric month (MM/M). For example,
* `y/MM/dd`, corresponding to a date like "1999/09/14".
*
* - `short` should contain year, numeric-month (MM/M), and day.
*
* For example, `M/d/yy`, corresponding to a date like "9/14/99".
* *
* @publicApi * @publicApi
*/ */
@ -257,23 +347,14 @@ export function getLocaleDateFormat(locale: string, width: FormatWidth): string
} }
/** /**
* Time format that depends on the locale. * Retrieves a localized time-value formatting string.
*
* The standard formats include four basic time formats:
* - `full` should contain hour (h/H), minute (mm), second (ss), and zone (zzzz).
* - `long` should contain hour, minute, second, and zone (z)
* - `medium` should contain hour, minute, second.
* - `short` should contain hour, minute.
*
* Note: The patterns depend on whether the main country using your language uses 12-hour time or
* not:
* - For 12-hour time, use a pattern like `hh:mm a` using h to mean a 12-hour clock cycle running
* 1 through 12 (midnight plus 1 minute is 12:01), or using K to mean a 12-hour clock cycle
* running 0 through 11 (midnight plus 1 minute is 0:01).
* - For 24-hour time, use a pattern like `HH:mm` using H to mean a 24-hour clock cycle running 0
* through 23 (midnight plus 1 minute is 0:01), or using k to mean a 24-hour clock cycle running
* 1 through 24 (midnight plus 1 minute is 24:01).
* *
* @param locale A locale code for the locale format rules to use.
* @param width The format type.
* @returns The localized formatting string.
* @see `FormatWidth`
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
* @publicApi * @publicApi
*/ */
export function getLocaleTimeFormat(locale: string, width: FormatWidth): string { export function getLocaleTimeFormat(locale: string, width: FormatWidth): string {
@ -282,27 +363,13 @@ export function getLocaleTimeFormat(locale: string, width: FormatWidth): string
} }
/** /**
* Date-time format that depends on the locale. * Retrieves a localized date-time formatting string.
* *
* The date-time pattern shows how to combine separate patterns for date (represented by {1}) * @param locale A locale code for the locale format rules to use.
* and time (represented by {0}) into a single pattern. It usually doesn't need to be changed. * @param width The format type.
* What you want to pay attention to are: * @returns The localized formatting string.
* - possibly removing a space for languages that don't use it, such as many East Asian languages * @see `FormatWidth`
* - possibly adding a comma, other punctuation, or a combining word * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* For example:
* - English uses `{1} 'at' {0}` or `{1}, {0}` (depending on date style), while Japanese uses
* `{1}{0}`.
* - An English formatted date-time using the combining pattern `{1}, {0}` could be
* `Dec 10, 2010, 3:59:49 PM`. Notice the comma and space between the date portion and the time
* portion.
*
* There are four formats (`full`, `long`, `medium`, `short`); the determination of which to use
* is normally based on the date style. For example, if the date has a full month and weekday
* name, the full combining pattern will be used to combine that with a time. If the date has
* numeric month, the short version of the combining pattern will be used to combine that with a
* time. English uses `{1} 'at' {0}` for full and long styles, and `{1}, {0}` for medium and short
* styles.
* *
* @publicApi * @publicApi
*/ */
@ -313,8 +380,12 @@ export function getLocaleDateTimeFormat(locale: string, width: FormatWidth): str
} }
/** /**
* Number symbol that can be used to replace placeholders in number formats. * Retrieves a localized number symbol that can be used to replace placeholders in number formats.
* See {@link NumberSymbol} for more information. * @param locale The locale code.
* @param symbol The symbol to localize.
* @returns The character for the localized symbol.
* @see `NumberSymbol`
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
* *
* @publicApi * @publicApi
*/ */
@ -332,17 +403,17 @@ export function getLocaleNumberSymbol(locale: string, symbol: NumberSymbol): str
} }
/** /**
* Number format that depends on the locale. * Retrieves a number format for a given locale.
* *
* Numbers are formatted using patterns, like `#,###.00`. For example, the pattern `#,###.00` * Numbers are formatted using patterns, like `#,###.00`. For example, the pattern `#,###.00`
* when used to format the number 12345.678 could result in "12'345,67". That would happen if the * when used to format the number 12345.678 could result in "12'345,678". That would happen if the
* grouping separator for your language is an apostrophe, and the decimal separator is a comma. * grouping separator for your language is an apostrophe, and the decimal separator is a comma.
* *
* <b>Important:</b> The characters `.` `,` `0` `#` (and others below) are special placeholders; * <b>Important:</b> The characters `.` `,` `0` `#` (and others below) are special placeholders
* they stand for the decimal separator, and so on, and are NOT real characters. * that stand for the decimal separator, and so on, and are NOT real characters.
* You must NOT "translate" the placeholders; for example, don't change `.` to `,` even though in * You must NOT "translate" the placeholders. For example, don't change `.` to `,` even though in
* your language the decimal point is written with a comma. The symbols should be replaced by the * your language the decimal point is written with a comma. The symbols should be replaced by the
* local equivalents, using the Number Symbols for your language. * local equivalents, using the appropriate `NumberSymbol` for your language.
* *
* Here are the special characters used in number patterns: * Here are the special characters used in number patterns:
* *
@ -352,13 +423,17 @@ export function getLocaleNumberSymbol(locale: string, symbol: NumberSymbol): str
* | , | Replaced by the "grouping" (thousands) separator. | * | , | Replaced by the "grouping" (thousands) separator. |
* | 0 | Replaced by a digit (or zero if there aren't enough digits). | * | 0 | Replaced by a digit (or zero if there aren't enough digits). |
* | # | Replaced by a digit (or nothing if there aren't enough). | * | # | Replaced by a digit (or nothing if there aren't enough). |
* | ¤ | This will be replaced by a currency symbol, such as $ or USD. | * | ¤ | Replaced by a currency symbol, such as $ or USD. |
* | % | This marks a percent format. The % symbol may change position, but must be retained. | * | % | Marks a percent format. The % symbol may change position, but must be retained. |
* | E | This marks a scientific format. The E symbol may change position, but must be retained. | * | E | Marks a scientific format. The E symbol may change position, but must be retained. |
* | ' | Special characters used as literal characters are quoted with ASCII single quotes. | * | ' | Special characters used as literal characters are quoted with ASCII single quotes. |
* *
* You can find more information * @param locale A locale code for the locale format rules to use.
* [on the CLDR website](http://cldr.unicode.org/translation/number-patterns) * @param type The type of numeric value to be formatted (such as `Decimal` or `Currency`.)
* @returns The localized format string.
* @see `NumberFormatStyle`
* @see [CLDR website](http://cldr.unicode.org/translation/number-patterns)
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
* *
* @publicApi * @publicApi
*/ */
@ -368,9 +443,13 @@ export function getLocaleNumberFormat(locale: string, type: NumberFormatStyle):
} }
/** /**
* The symbol used to represent the currency for the main country using this locale (e.g. $ for * Retrieves the symbol used to represent the currency for the main country
* the locale en-US). * corresponding to a given locale. For example, '$' for `en-US`.
* The symbol will be `null` if the main country cannot be determined. *
* @param locale A locale code for the locale format rules to use.
* @returns The localized symbol character,
* or `null` if the main country cannot be determined.
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
* *
* @publicApi * @publicApi
*/ */
@ -380,9 +459,12 @@ export function getLocaleCurrencySymbol(locale: string): string|null {
} }
/** /**
* The name of the currency for the main country using this locale (e.g. 'US Dollar' for the locale * Retrieves the name of the currency for the main country corresponding
* en-US). * to a given locale. For example, 'US Dollar' for `en-US`.
* The name will be `null` if the main country cannot be determined. * @param locale A locale code for the locale format rules to use.
* @returns The currency name,
* or `null` if the main country cannot be determined.
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
* *
* @publicApi * @publicApi
*/ */
@ -392,7 +474,10 @@ export function getLocaleCurrencyName(locale: string): string|null {
} }
/** /**
* Returns the currency values for the locale * Retrieves the currency values for a given locale.
* @param locale A locale code for the locale format rules to use.
* @returns The currency values.
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*/ */
function getLocaleCurrencies(locale: string): {[code: string]: CurrenciesSymbols} { function getLocaleCurrencies(locale: string): {[code: string]: CurrenciesSymbols} {
const data = findLocaleData(locale); const data = findLocaleData(locale);
@ -400,8 +485,12 @@ function getLocaleCurrencies(locale: string): {[code: string]: CurrenciesSymbols
} }
/** /**
* The locale plural function used by ICU expressions to determine the plural case to use. * Retrieves the plural function used by ICU expressions to determine the plural case to use
* See {@link NgPlural} for more information. * for a given locale.
* @param locale A locale code for the locale format rules to use.
* @returns The plural function for the locale.
* @see `NgPlural`
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
* *
* @publicApi * @publicApi
*/ */
@ -418,17 +507,24 @@ function checkFullData(data: any) {
} }
/** /**
* Rules used to determine which day period to use (See `dayPeriods` below). * Retrieves locale-specific rules used to determine which day period to use
* The rules can either be an array or a single value. If it's an array, consider it as "from" * when more than one period is defined for a locale.
* and "to". If it's a single value then it means that the period is only valid at this exact
* value.
* There is always the same number of rules as the number of day periods, which means that the
* first rule is applied to the first day period and so on.
* You should fallback to AM/PM when there are no rules available.
* *
* Note: this is only available if you load the full locale data. * There is a rule for each defined day period. The
* See the ["I18n guide"](guide/i18n#i18n-pipes) to know how to import additional locale * first rule is applied to the first day period and so on.
* data. * Fall back to AM/PM when no rules are available.
*
* A rule can specify a period as time range, or as a single time value.
*
* This functionality is only available when you have loaded the full locale data.
* See the ["I18n guide"](guide/i18n#i18n-pipes).
*
* @param locale A locale code for the locale format rules to use.
* @returns The rules for the locale, a single time value or array of *from-time, to-time*,
* or null if no periods are available.
*
* @see `getLocaleExtraDayPeriods()`
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
* *
* @publicApi * @publicApi
*/ */
@ -445,15 +541,19 @@ export function getLocaleExtraDayPeriodRules(locale: string): (Time | [Time, Tim
} }
/** /**
* Day Periods indicate roughly how the day is broken up in different languages (e.g. morning, * Retrieves locale-specific day periods, which indicate roughly how a day is broken up
* noon, afternoon, midnight, ...). * in different languages.
* You should use the function {@link getLocaleExtraDayPeriodRules} to determine which period to * For example, for `en-US`, periods are morning, noon, afternoon, evening, and midnight.
* use.
* You should fallback to AM/PM when there are no day periods available.
* *
* Note: this is only available if you load the full locale data. * This functionality is only available when you have loaded the full locale data.
* See the ["I18n guide"](guide/i18n#i18n-pipes) to know how to import additional locale * See the ["I18n guide"](guide/i18n#i18n-pipes).
* data. *
* @param locale A locale code for the locale format rules to use.
* @param formStyle The required grammatical form.
* @param width The required character width.
* @returns The translated day-period strings.
* @see `getLocaleExtraDayPeriodRules()`
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
* *
* @publicApi * @publicApi
*/ */
@ -470,11 +570,15 @@ export function getLocaleExtraDayPeriods(
} }
/** /**
* Returns the first value that is defined in an array, going backwards. * Retrieves the first value that is defined in an array, going backwards from an index position.
* *
* To avoid repeating the same data (e.g. when "format" and "standalone" are the same) we only * To avoid repeating the same data (as when the "format" and "standalone" forms are the same)
* add the first one to the locale data arrays, the other ones are only defined when different. * add the first value to the locale data arrays, and add other values only if they are different.
* We use this function to retrieve the first defined value. *
* @param data The data array to retrieve from.
* @param index A 0-based index into the array to start from.
* @returns The value immediately before the given index position.
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
* *
* @publicApi * @publicApi
*/ */
@ -488,7 +592,7 @@ function getLastDefinedValue<T>(data: T[], index: number): T {
} }
/** /**
* A representation of the time with hours and minutes * Represents a time value with hours and minutes.
* *
* @publicApi * @publicApi
*/ */
@ -498,7 +602,7 @@ export type Time = {
}; };
/** /**
* Extract the hours and minutes from a string like "15:45" * Extracts the hours and minutes from a string like "15:45"
*/ */
function extractTime(time: string): Time { function extractTime(time: string): Time {
const [h, m] = time.split(':'); const [h, m] = time.split(':');
@ -506,7 +610,11 @@ function extractTime(time: string): Time {
} }
/** /**
* Finds the locale data for a locale id * Finds the locale data for a given locale.
*
* @param locale The locale code.
* @returns The locale data.
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
* *
* @publicApi * @publicApi
*/ */
@ -534,9 +642,17 @@ export function findLocaleData(locale: string): any {
} }
/** /**
* Returns the currency symbol for a given currency code, or the code if no symbol available * Retrieves the currency symbol for a given currency code.
* (e.g.: format narrow = $, format wide = US$, code = USD) *
* If no locale is provided, it uses the locale "en" by default * For example, for the default `en-US` locale, the code `USD` can
* be represented by the narrow symbol `$` or the wide symbol `US$`.
*
* @param code The currency code.
* @param format The format, `wide` or `narrow`.
* @param locale A locale code for the locale format rules to use.
*
* @returns The symbol, or the currency code if no symbol is available.0
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
* *
* @publicApi * @publicApi
*/ */
@ -555,8 +671,12 @@ export function getCurrencySymbol(code: string, format: 'wide' | 'narrow', local
const DEFAULT_NB_OF_CURRENCY_DIGITS = 2; const DEFAULT_NB_OF_CURRENCY_DIGITS = 2;
/** /**
* Returns the number of decimal digits for the given currency. * Reports the number of decimal digits for a given currency.
* Its value depends upon the presence of cents in that particular currency. * The value depends upon the presence of cents in that particular currency.
*
* @param code The currency code.
* @returns The number of decimal digits, typically 0 or 2.
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
* *
* @publicApi * @publicApi
*/ */

20
packages/core/src/di/injector_compatibility.ts
View File

@ -70,18 +70,24 @@ export function injectInjectorOnly<T>(
/** /**
* Injects a token from the currently active injector. * Injects a token from the currently active injector.
* Must be used in the context of a factory function such as one defined for an
* `InjectionToken`. Throws an error if not called from such a context.
* *
* This function must be used in the context of a factory function such as one defined for an * Within such a factory function, using this function to request injection of a dependency
* `InjectionToken`, and will throw an error if not called from such a context. * is faster and more type-safe than providing an additional array of dependencies
* (as has been common with `useFactory` providers).
*
* @param token The injection token for the dependency to be injected.
* @param flags Optional flags that control how injection is executed.
* The flags correspond to injection strategies that can be specified with
* parameter decorators `@Host`, `@Self`, `@SkipSef`, and `@Optional`.
* @returns True if injection is successful, null otherwise.
* *
* @usageNotes * @usageNotes
*
* ### Example * ### Example
* *
* {@example core/di/ts/injector_spec.ts region='ShakeableInjectionToken'} * {@example core/di/ts/injector_spec.ts region='ShakableInjectionToken'}
*
* Within such a factory function `inject` is utilized to request injection of a dependency, instead
* of providing an additional array of dependencies as was common to do with `useFactory` providers.
* `inject` is faster and more type-safe.
* *
* @publicApi * @publicApi
*/ */