globalize-rpk 1.7.1 → 1.7.2

package/doc/api/date/date-to-parts-formatter.md

@@ -0,0 +1,176 @@
+## .dateToPartsFormatter( [options] ) ➜ function( value )
+
+Return a function that formats a date into parts tokens according to the given `options`. The default formatting is numeric year, month, and day (i.e., `{ skeleton: "yMd" }`.
+
+The returned function is invoked with one argument: the Date instance `value` to be formatted.
+
+### Parameters
+
+#### options
+
+Please, see [.dateFormatter() options](./date-formatter.md#parameters).
+
+#### value
+
+Date instance to be formatted, eg. `new Date()`;
+
+### Returns
+
+An Array of objects containing the formatted date in parts. The returned structure looks like this:
+
+```js
+[
+  { type: "day", value: "17" },
+  { type: "weekday", value: "Monday" }
+]
+```
+
+Possible types are the following:
+
+- `day`
+
+  The string used for the day, e.g., `"17"`, `"١٦"`.
+
+- `dayperiod`
+
+  The string used for the day period, e.g., `"AM"`, `"PM"`.
+
+- `era`
+
+  The string used for the era, e.g., `"AD"`, `"d. C."`.
+
+- `hour`
+
+  The string used for the hour, e.g., `"3"`, `"03"`.
+
+- `literal`
+
+  The string used for separating date and time values, e.g., `"/"`, `", "`,
+  `"o'clock"`, `" de "`.
+
+- `minute`
+
+  The string used for the minute, e.g., `"00"`.
+
+- `month`
+
+  The string used for the month, e.g., `"12"`.
+
+- `second`
+
+  The string used for the second, e.g., `"07"` or `"42"`.
+
+- `zone`
+
+  The string used for the name of the time zone, e.g., `"EST".`
+
+- `weekday`
+
+  The string used for the weekday, e.g., `"M"`, `"Monday"`, `"Montag".`
+
+- `year`
+
+  The string used for the year, e.g., `"2012"`, `"96".`
+
+
+### Example
+
+Prior to using any date methods, you must load `cldr/main/{locale}/ca-gregorian.json`, `cldr/main/{locale}/timeZoneNames.json`, `cldr/supplemental/timeData.json`, `cldr/supplemental/weekData.json`, and the CLDR content required by the number module. Read [CLDR content][] if you need more information.
+
+[CLDR content]: ../../../README.md#2-cldr-content
+
+You can use the static method `Globalize.dateToPartsFormatter()`, which uses the default locale.
+
+```javascript
+var formatter;
+
+Globalize.locale( "en" );
+formatter = Globalize.dateToPartsFormatter();
+
+formatter( new Date( 2010, 10, 30 ) );
+// > [
+//   { "type": "month", "value": "11" },
+//   { "type": "literal", "value": "/" },
+//   { "type": "day", "value": "30" },
+//   { "type": "literal", "value": "/" },
+//   { "type": "year", "value": "2010" }
+// ]
+```
+
+You can use the instance method `.dateToPartsFormatter()`, which uses the instance locale.
+
+```javascript
+var enFormatter = Globalize( "en" ).dateToPartsFormatter(),
+  deFormatter = Globalize( "de" ).dateToPartsFormatter();
+
+enFormatter( new Date( 2010, 10, 30 ) );
+// > [
+//   { "type": "month", "value": "11" },
+//   { "type": "literal", "value": "/" },
+//   { "type": "day", "value": "30" },
+//   { "type": "literal", "value": "/" },
+//   { "type": "year", "value": "2010" }
+// ]
+
+deFormatter( new Date( 2010, 10, 30 ) );
+// > [
+//   { type: 'day', value: '30' },
+//   { type: 'literal', value: '.' },
+//   { type: 'month', value: '11' },
+//   { type: 'literal', value: '.' },
+//   { type: 'year', value: '2010' }
+// ]
+```
+
+The information is available separately and it can be formatted and concatenated again in a customized way. For example by using [`Array.prototype.map()`][], [arrow functions][], a [switch statement][], [template literals][], and [`Array.prototype.reduce()`][].
+
+[`Array.prototype.map()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map
+[arrow functions]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions
+[switch statement]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/switch
+[template literals]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals
+[`Array.prototype.reduce()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce
+
+```javascript
+var formatter;
+
+Globalize.locale( "en" );
+formatter = Globalize.dateToPartsFormatter({datetime: "short"});
+
+formatter( new Date( 2010, 10, 30, 17, 55 ) ).map(({type, value}) => {
+  switch ( type ) {
+    case "year": return `<strong>${value}</strong>`;
+    default: return value;
+  }
+}).join( "" );
+// > "11/30/<strong>10</strong>, 5:55 PM"
+```
+
+Please, see [.dateFormatter() example](./date-formatter.md#example) for additional examples such as using `date`, `time`, `datetime`, and `skeleton` options.
+
+For improved performance on iterations, first create the formatter. Then, reuse it on each loop.
+
+```javascript
+// In an application, this array could have a few hundred entries
+var dates = [ new Date( 2010, 10, 30, 17, 55 ), new Date( 2015, 3, 18, 4, 25 ) ];
+var formatter = Globalize( "en" ).dateToPartsFormatter({ time: "short" });
+
+var formattedDates = dates.map(function( date ) {
+  return formatter( date );
+});
+// > [
+//   [
+//     { "type": "hour", "value": "5" },
+//     { "type": "literal", "value": ":" },
+//     { "type": "minute", "value": "55" },
+//     { "type": "literal", "value": " " },
+//     { "type": "dayperiod", "value": "PM" }
+//   ],
+//   [
+//     { "type": "hour", "value": "4" },
+//     { "type": "literal", "value": ":" },
+//     { "type": "minute", "value": "25" },
+//     { "type": "literal", "value": " " },
+//     { "type": "dayperiod", "value": "AM" }
+//   ]
+// ]
+```

package/doc/api/date/load-iana-time-zone.md

@@ -0,0 +1,29 @@
+## Globalize.loadTimeZone( ianaTzData )
+
+This method allows you to load IANA time zone data to enable `options.timeZone` feature on date formatters and parsers.
+
+### Parameters
+
+#### ianaTzData
+
+A JSON object with zdumped IANA timezone data. Get the data via [`iana-tz-data`](https://github.com/rxaviers/iana-tz-data).
+
+### Example
+
+```javascript
+Globalize.loadTimeZone({
+  "zoneData": {
+    ...
+    "America": {
+      ...
+      "New_York": {
+        abbrs: [],
+        untils: [],
+        offsets: [],
+        isdsts: []
+      }
+      ...
+    }
+  }
+});
+```

package/doc/api/message/load-messages.md

@@ -0,0 +1,105 @@
+## .loadMessages( json )
+
+Load messages data.
+
+The first level of keys must be locales. For example:
+
+```
+{
+  en: {
+    hello: "Hello"
+  },
+  pt: {
+    hello: "Olá"
+  }
+}
+```
+
+ICU MessageFormat pattern is supported: variable replacement, gender and plural inflections. For more information see [`.messageFormatter( path ) ➡ function([ variables ])`](./message-formatter.md).
+
+The provided messages are stored along side other cldr data, under the "globalize-messages" key. This allows Globalize to reuse the traversal methods provided by cldrjs. You can inspect this data using `cldrjs.get("globalize-messages")`.
+
+### Parameters
+
+#### json
+
+JSON object of messages data. Keys can use any character, except `/`, `{` and `}`. Values (i.e., the message content itself) can contain any character.
+
+### Example
+
+```javascript
+Globalize.loadMessages({
+  pt: {
+    greetings: {
+      hello: "Olá",
+      bye: "Tchau"
+    }
+  }
+});
+
+Globalize( "pt" ).formatMessage( "greetings/hello" );
+// > Olá
+```
+
+#### Multiline strings
+
+Use Arrays as a convenience for multiline strings. The lines will be joined by a space.
+
+```javascript
+Globalize.loadMessages({
+  en: {
+    longText: [
+      "Lorem ipsum dolor sit amet, consectetur adipisicing elit. Eligendi non",
+      "quis exercitationem culpa nesciunt nihil aut nostrum explicabo",
+      "reprehenderit optio amet ab temporibus asperiores quasi cupiditate.",
+      "Voluptatum ducimus voluptates voluptas?"
+    ]
+  }
+});
+
+Globalize( "en" ).formatMessage( "longText" );
+// > "Lorem ipsum dolor sit amet, consectetur adipisicing elit. Eligendi non quis exercitationem culpa nesciunt nihil aut nostrum explicabo reprehenderit optio amet ab temporibus asperiores quasi cupiditate. Voluptatum ducimus voluptates voluptas?"
+```
+
+#### Messages inheritance
+
+It's possible to inherit messages, for example:
+
+```javascript
+Globalize.loadMessages({
+  root: {
+    amen: "Amen"
+  },
+  de: {},
+  en: {},
+  "en-GB": {},
+  fr: {},
+  pt: {
+    amen: "Amém"
+  },
+  "pt-PT": {}
+});
+
+Globalize( "de" ).formatMessage( "amen" );
+// > "Amen"
+
+Globalize( "en" ).formatMessage( "amen" );
+// > "Amen"
+
+Globalize( "en-GB" ).formatMessage( "amen" );
+// > "Amen"
+
+Globalize( "fr" ).formatMessage( "amen" );
+// > "Amen"
+
+Globalize( "pt-PT" ).formatMessage( "amen" );
+// > "Amém"
+```
+
+Note that `de`, `en`, `en-GB`, `fr`, and `pt-PT` are empty. `.formatMessage()` inherits `pt-PT` messages from `pt` (`pt-PT` ➡ `pt`), and it inherits the other messages from root, eg. `en-GB` ➡ `en-001` ➡ `en` ➡ `root`. Yes, `root` is the last bundle of the parent lookup.
+
+Attention: On browsers, message inheritance only works if the optional dependency `cldr/unresolved` is loaded.
+
+```html
+<script src="cldr/unresolved.js"></script>
+```

package/doc/api/message/message-formatter.md

@@ -0,0 +1,208 @@
+## .messageFormatter( path ) ➡ function([ variables ])
+
+Return a function that formats a message (using ICU message format pattern) given its path and a set of variables into a user-readable string. It supports pluralization and gender inflections.
+
+Use [`Globalize.loadMessages( json )`](./load-messages.md) to load
+messages data.
+
+### Parameters
+
+#### path
+
+String or Array containing the path of the message content, eg., `"greetings/bye"`, or `[ "greetings", "bye" ]`.
+
+#### variables
+
+Optional. Variables can be Objects, where each property can be referenced by name inside a message; or Arrays, where each entry of the Array can be used inside a message, using numeric indices. When passing one or more arguments of other types, they're converted to an Array and used as such.
+
+### Example
+
+You can use the static method `Globalize.messageFormatter()`, which uses the default locale.
+
+```javascript
+var formatter;
+
+Globalize.loadMessages({
+  pt: {
+    greetings: {
+      bye: "Tchau"
+    }
+  }
+});
+
+Globalize.locale( "pt" );
+formatter = Globalize.messageFormatter( "greetings/bye" );
+
+formatter();
+// > "Tchau"
+```
+
+You can use the instance method `.messageFormatter()`, which uses the instance locale.
+
+```javascript
+var pt = new Globalize( "pt" ),
+  formatter = pt.messageFormatter( "greetings/bye" );
+
+formatter();
+// > "Tchau"
+```
+
+#### Simple Variable Replacement
+
+```javascript
+var formatter;
+
+Globalize.loadMessages({
+  en: {
+    hello: "Hello, {0} {1} {2}",
+    hey: "Hey, {first} {middle} {last}"
+  }
+});
+
+formatter = Globalize( "en" ).messageFormatter( "hello" );
+
+// Numbered variables using Array.
+formatter([ "Wolfgang", "Amadeus", "Mozart" ]);
+// > "Hello, Wolfgang Amadeus Mozart"
+
+// Numbered variables using function arguments.
+formatter( "Wolfgang", "Amadeus", "Mozart" );
+// > "Hello, Wolfgang Amadeus Mozart"
+
+// Named variables using Object key-value pairs.
+formatter = Globalize( "en" ).messageFormatter( "hey" );
+formatter({
+  first: "Wolfgang",
+  middle: "Amadeus",
+  last: "Mozart"
+});
+// > "Hey, Wolfgang Amadeus Mozart"
+```
+
+#### Gender inflections
+
+`select` can be used to format any message variations that works like a switch.
+
+```javascript
+var formatter;
+
+// Note you can define multiple lines message using an Array of Strings.
+Globalize.loadMessages({
+  en: {
+    party: [
+      "{hostGender, select,",
+      "  female {{host} invites {guest} to her party}",
+      "    male {{host} invites {guest} to his party}",
+      "   other {{host} invites {guest} to their party}",
+      "}"
+    ]
+  }
+});
+
+formatter = Globalize( "en" ).messageFormatter( "party" );
+
+formatter({
+  guest: "Mozart",
+  host: "Beethoven",
+  hostGender: "male"
+});
+// > "Beethoven invites Mozart to his party"
+```
+
+#### Plural inflections
+
+It uses the plural forms `zero`, `one`, `two`, `few`, `many`, or `other` (required). Note English only uses `one` and `other`. So, including `zero` will never get called, even when the number is 0. For more information see [`.pluralGenerator()`](../plural/plural-generator.md).
+
+```javascript
+var numberFormatter, taskFormatter,
+  en = new Globalize( "en" );
+
+// Note you can define multiple lines message using an Array of Strings.
+Globalize.loadMessages({
+  en: {
+    task: [
+      "You have {count, plural,",
+      "    one {one task}",
+      "  other {{formattedCount} tasks}",
+      "} remaining"
+    ]
+  }
+});
+
+numberFormatter = en.numberFormatter();
+taskFormatter = en.messageFormatter( "task" );
+
+taskFormatter({
+  count: 1000,
+  formattedCount: numberFormatter( 1000 )
+});
+// > "You have 1,000 tasks remaining"
+```
+
+Literal numeric keys can be used in `plural` to match single, specific numbers.
+
+```javascript
+var taskFormatter,
+  en = new Globalize( "en" );
+
+// Note you can define multiple lines message using an Array of Strings.
+Globalize.loadMessages({
+  en: {
+    task: [
+      "You have {count, plural,",
+      "     =0 {no tasks}",
+      "    one {one task}",
+      "  other {{formattedCount} tasks}",
+      "} remaining"
+    ]
+  }
+});
+
+taskFormatter = Globalize( "en" ).messageFormatter( "task" );
+
+taskFormatter({
+  count: 0,
+  formattedCount: en.numberFormatter( 0 )
+});
+// > "You have no tasks remaining"
+```
+
+You may find useful having the plural forms calculated with an offset applied.
+Use `#` to output the resulting number. Note literal numeric keys do NOT use the
+offset value.
+
+```javascript
+var likeFormatter,
+  en = new Globalize( "en" );
+
+Globalize.loadMessages({
+  en: {
+    likeIncludingMe: [
+      "{0, plural, offset:1",
+      "     =0 {Be the first to like this}",
+      "     =1 {You liked this}",
+      "    one {You and someone else liked this}",
+      "  other {You and # others liked this}",
+      "}"
+    ]
+  }
+});
+
+likeFormatter = Globalize( "en" ).messageFormatter( "likeIncludingMe" );
+
+likeFormatter( 0 );
+// > "Be the first to like this"
+
+likeFormatter( 1 );
+// > "You liked this"
+
+likeFormatter( 2 );
+// > "You and someone else liked this"
+
+likeFormatter( 3 );
+// > "You and 2 others liked this"
+```
+
+Read on [SlexAxton/messageFormatter.js][] for more information on regard of ICU MessageFormat.
+
+[SlexAxton/messageFormatter.js]: https://github.com/SlexAxton/messageformat.js/#no-frills