Internationalized docs #2772
Internationalized docs #2772
Conversation
|
Build successful! 🎉 |
| --- | ||
| category: Libraries | ||
| description: Internationalization utilities | ||
| --- |
There was a problem hiding this comment.
We will need some way to prevent this page from going out if we merge it before we are ready for the release.
| { | ||
| title: 'Time zones', | ||
| description: 'The @internationalized/timezone package includes data about time zones, including their geography, translated city names, and more.' | ||
| }, |
There was a problem hiding this comment.
Need to actually write the docs for these 😉
There was a problem hiding this comment.
Is that why @internationlized/timezone isn't a link?
There was a problem hiding this comment.
Well, it doesn't exist yet. 😄
|
Build successful! 🎉 |
|
|
||
| # @internationalized/date | ||
|
|
||
| The `@internationalized/date` package provides objects and functions for representing and manipulating dates and times in a locale aware manner. |
There was a problem hiding this comment.
| The `@internationalized/date` package provides objects and functions for representing and manipulating dates and times in a locale aware manner. | |
| The `@internationalized/date` package provides objects and functions for representing and manipulating dates and times in a locale-aware manner. |
There was a problem hiding this comment.
There is probably some of these in a bunch of places, might not be a big enough deal to change though.
| ## Features | ||
|
|
||
| * **Advanced formatting** – Formatting and parsing decimals, percentages, currency values, and unit values are supported. | ||
| * **Locale aware** – Numbers are formatted and parsed according to the locale expectations, including decimal characters and separators, percent signs, unit and currency symbols, and more. |
There was a problem hiding this comment.
| * **Locale aware** – Numbers are formatted and parsed according to the locale expectations, including decimal characters and separators, percent signs, unit and currency symbols, and more. | |
| * **Locale-aware** – Numbers are formatted and parsed according to the locale expectations, including decimal characters and separators, percent signs, unit and currency symbols, and more. |
| * **International calendars** – Support for 13 calendar systems used around the world, including Gregorian, Buddhist, Islamic, Persian, and more. | ||
| * **Manipulation** – Add and subtract durations, set and cycle fields, and more. | ||
| * **Conversion** – Convert between calendar systems, time zones, string representations, and object types. | ||
| * **Queries** – Compare dates and times for ordering or full/partial equality. Determine locale specific metadata such as day of week, weekend/weekday, etc. |
There was a problem hiding this comment.
| * **Queries** – Compare dates and times for ordering or full/partial equality. Determine locale specific metadata such as day of week, weekend/weekday, etc. | |
| * **Queries** – Compare dates and times for ordering or full/partial equality. Determine locale-specific metadata such as day of week, weekend/weekday, etc. |
|
|
||
| `NumberParser` is designed to validate and parse numbers from user input according to a specific locale and format. It supports several different numbering systems including the Latin, Arabic, and Han positional numbering systems, as well as parsing decimals, percentages, currencies, and unit values. The numbering system is automatically detected from the input string. This means that users may input numbers in a different numbering system than the default for their locale, e.g. a Latin number in an Arabic locale. | ||
|
|
||
| Parsing numbers while taking into account all locale specific detail is quite complex and error-prone. `NumberParser` uses information about the locale and expected format for a number in order to parse it correctly. This means it is somewhat strict about the accepted formats. It is not designed to handle use cases where the user can enter numbers in an unknown format (e.g. either a unit value _or_ a percentage), this must be known up front or selected via an external UI control. |
There was a problem hiding this comment.
| Parsing numbers while taking into account all locale specific detail is quite complex and error-prone. `NumberParser` uses information about the locale and expected format for a number in order to parse it correctly. This means it is somewhat strict about the accepted formats. It is not designed to handle use cases where the user can enter numbers in an unknown format (e.g. either a unit value _or_ a percentage), this must be known up front or selected via an external UI control. | |
| Parsing numbers while taking into account all locale-specific detail is quite complex and error-prone. `NumberParser` uses information about the locale and expected format for a number in order to parse it correctly. This means it is somewhat strict about the accepted formats. It is not designed to handle use cases where the user can enter numbers in an unknown format (e.g. either a unit value _or_ a percentage), this must be known up front or selected via an external UI control. |
|
|
||
| ## Introduction | ||
|
|
||
| While the Gregorian calendar is the most commonly used, many other calendar systems are used throughout the world. The `Calendar` interface is used to represent calendar systems in the `@internationalized/date` library. It encapsulates information such as the number of days in a month, the number of months in a year, and the list of eras in a calendar system, as well as methods to that handle correct arithmetic of dates in that calendar system, as well as converting dates between calendar systems. Many implementations of this interface are provided in `@internationalized/date` to handle the most commonly used calendar systems. |
There was a problem hiding this comment.
| While the Gregorian calendar is the most commonly used, many other calendar systems are used throughout the world. The `Calendar` interface is used to represent calendar systems in the `@internationalized/date` library. It encapsulates information such as the number of days in a month, the number of months in a year, and the list of eras in a calendar system, as well as methods to that handle correct arithmetic of dates in that calendar system, as well as converting dates between calendar systems. Many implementations of this interface are provided in `@internationalized/date` to handle the most commonly used calendar systems. | |
| While the Gregorian calendar is the most commonly used, many other calendar systems are used throughout the world. The `Calendar` interface is used to represent calendar systems in the `@internationalized/date` library. It encapsulates information such as the number of days in a month, the number of months in a year, and the list of eras in a calendar system, as well as methods that handle correct arithmetic of dates in that calendar system, as well as converting dates between calendar systems. Many implementations of this interface are provided in `@internationalized/date` to handle the most commonly used calendar systems. |
| date.set({hour: 30}); // 2022-02-03T23:45[America/Los_Angeles] | ||
| ``` | ||
|
|
||
| Setting fields is zome zone aware. When setting fields around a daylight saving time transition, the UTC offset will be adjusted accordingly. For example, when changing the `day` field from before a daylight saving transition to after, the time remains the same but the UTC offset changes. |
There was a problem hiding this comment.
| Setting fields is zome zone aware. When setting fields around a daylight saving time transition, the UTC offset will be adjusted accordingly. For example, when changing the `day` field from before a daylight saving transition to after, the time remains the same but the UTC offset changes. | |
| Setting fields is zone aware. When setting fields around a daylight saving time transition, the UTC offset will be adjusted accordingly. For example, when changing the `day` field from before a daylight saving transition to after, the time remains the same but the UTC offset changes. |
LFDanLu
left a comment
LFDanLu
left a comment
There was a problem hiding this comment.
Will follow up with NumberParser and NumberFormatter review
|
NumberParser and NumberFormatter docs look good |
ktabors
left a comment
ktabors
left a comment
There was a problem hiding this comment.
This is a lot fo documentation you wrote. It looks really good and I learned some stuff. Thank you!
| { | ||
| title: 'Time zones', | ||
| description: 'The @internationalized/timezone package includes data about time zones, including their geography, translated city names, and more.' | ||
| }, |
There was a problem hiding this comment.
Is that why @internationlized/timezone isn't a link?
| A library of framework-agnostic internationalization utilities for the web. | ||
|
|
||
| <p className={clsx(typographyStyles['spectrum-Body2'], styles.homeLinks)}> | ||
| <a href="https://github.com/adobe/react-spectrum" className={clsx(linkStyle['spectrum-Link'], styles.link)}>GitHub</a> |
There was a problem hiding this comment.
Should this link be more specific to https://github.com/adobe/react-spectrum/tree/main/packages/%40internationalized?
There was a problem hiding this comment.
maybe if we had a readme there, but otherwise it kinda dumps you somewhere with no info...
| description: Internationalization utilities | ||
| --- | ||
|
|
||
| # Internationalized |
There was a problem hiding this comment.
Not sure where this question should go. Do we need an Introduction section with a getting started page in the sidenav like we have for the other packages? You did create introduction pages for each sub part of the package. But these are different then the getting started pages in the introduction sections. For example the Introduction pages have the headers with links to npmjs and github which the getting started pages don't.
Landing at the index.html for this section, that looked similar to docs landing page was confusing because it makes the date, number, and timezone fee like peers to spectrum, aria and stately. However the sidenav made them look like sections of components within spectrum, aria, and stately. And the intro pages have links to the npmjs like they are a component. Combined with introductions being in each section in the sidenav gives the feeling that the informational architecture for this part of the docs is inconsistent and confusing.
|
|
||
| ## Introduction | ||
|
|
||
| A `Time` object represents a clock time without any date components. If you need to refer to a time on a specific date, use a [CalendarDateTime](CalendarDateTime.html) or [ZonedDateTime](ZonedDateTime.html) instead. |
There was a problem hiding this comment.
Last time I saw a mirrored first sentence they was additional info at the end of the sentence. This one is exactly the same.
| let date = parseAbsoluteToLocal('2021-11-07T07:45:00Z'); | ||
| ``` | ||
|
|
||
| Once you have a `ZonedDateTime` object, you can read its properties, or manipulate it as described in the [Manipulating dates](#manipulating-dates) section below. You can also convert it to an ISO 8601 string, native JavaScript `Date` object, or another representation. See the [Conversion](#conversion) section below for details. |
There was a problem hiding this comment.
Seems unnecessary to repeat since there is already a link on the first instance above?
| date.subtract({minutes: 30}); // 2022-02-03T09:15[America/Los_Angeles] | ||
| ``` | ||
|
|
||
| Adding or subtracting a duration that goes beyond the limits of a particular field will cause the date to be _balanced_. For example, adding one day to August 31st results in September 1st. In addition, if adding or subtracting one field causes another to be invalid, the date will be _constrained_. For example, adding one month to August 31st results in September 30th because September 31st does not exist. |
There was a problem hiding this comment.
I'm looking at the next paragraph and wondering if we should use quotes instead of italics. I'm concerned about another formatting style to "confuse" readers and another rule for us to follow.
| ); // false | ||
| ``` | ||
|
|
||
| A similar set of functions is also available that does not convert between calendar systems and requires the calendars to be equal. |
There was a problem hiding this comment.
In other places you have examples of isEqualXXXX.
There was a problem hiding this comment.
Yeah it's just harder to show because ZonedDateTime has so many arguments for the constructor.
|
Build successful! 🎉 |
snowystinger
left a comment
snowystinger
left a comment
There was a problem hiding this comment.
There's a number of places where // => output is missing the =>
| }, | ||
| { | ||
| title: 'Numbers', | ||
| description: <>The <a href="./number/index.html">@internationalized/number</a> package implements international number formatting and parsing, including support for multiple numbering systems, currencies, percentages, units, other formatting options.</>, |
There was a problem hiding this comment.
| description: <>The <a href="./number/index.html">@internationalized/number</a> package implements international number formatting and parsing, including support for multiple numbering systems, currencies, percentages, units, other formatting options.</>, | |
| description: <>The <a href="./number/index.html">@internationalized/number</a> package implements international number formatting and parsing, including support for multiple numbering systems, currencies, percentages, units, and other formatting options.</>, |
| } | ||
|
|
||
| /** | ||
| * The Ethipic calendar system is the official calendar used in Ethiopia. |
There was a problem hiding this comment.
| * The Ethipic calendar system is the official calendar used in Ethiopia. | |
| * The Ethiopic calendar system is the official calendar used in Ethiopia. |
| /** | ||
| * The Taiwanese calendar is the same as the Gregorian calendar, but years | ||
| * are numbered starting from 1912 (Gregorian). Two eras are supported: | ||
| * 'before_minguo' and 'mingo'. |
There was a problem hiding this comment.
| * 'before_minguo' and 'mingo'. | |
| * 'before_minguo' and 'minguo'. |
I think?
|
Build successful! 🎉 |
|
Build successful! 🎉 |
|
Build successful! 🎉 |
|
Should be ok. I changed some things so the docs won't go out to prod immediately. |
|
Build successful! 🎉 |
|
Build successful! 🎉 |
snowystinger
left a comment
snowystinger
left a comment
There was a problem hiding this comment.
I've resolved the remainder of my comments 👍🏻
This adds a section for the
@internationalizedfamily of libraries to the documentation website. Currently, it covers the date package, but more will be added.Note that the docs for several of the objects are intentionally repetitive. We could also consider moving the functions somewhere common, but I tend to expect most readers to just look at one page and not navigate around too much so I think repeating some content is ok. Curious to hear other opinions.