-
Notifications
You must be signed in to change notification settings - Fork 326
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: global date time formatting through i18n (#2552)
* feat: global date time formatting through i18n * fix: build and lint issues * fix: StickyHeader code * fix: broken translations for date time * fix: broken translations for date time * fix: build issues * fix: remove timestampTranslationKey prop * tests: fix broken tests * tests: fix broken tests * fix: memoize the getDatestring logic * fix: memoize the getDatestring logic * fix: memoize the getDatestring logic * fix: translations test * fix: add tests * fix: use i18n-parser for build-translations and improve related scripts * fix: use i18n-parser for build-translations and improve related scripts * fix: prettier config * debug commit * debug commit * Delete package/src/i18n/pt-BR.json * debug commit * debug commit * set keepRemoved true * fix: build config * fix: build config
- Loading branch information
Showing
52 changed files
with
787 additions
and
329 deletions.
There are no files selected for viewing
129 changes: 129 additions & 0 deletions
129
docusaurus/docs/reactnative/guides/date-time-formatting.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,129 @@ | ||
| --- | ||
| id: date-time-formatting | ||
| title: Date and time formatting | ||
| --- | ||
|
|
||
| In this guide we will learn how date a time formatting can be customized within SDK's components. | ||
|
|
||
| ## SDK components displaying date & time | ||
|
|
||
| The following components provided by the SDK display datetime: | ||
|
|
||
| - `ChannelPreviewStatus` - Component showing last message date and time in `ChannelList`. | ||
| - `ImageGalleryHeader` - Component showing the header in the `ImageGallery`. | ||
| - `InlineDateSeparator` - Component separating groups of messages in `MessageList`. | ||
| - `MessageEditedTimestamp` - Component showing edited message time when clicked on an edited message. | ||
| - `MessageSystem` - Component showing system message. | ||
| - `MessageTimestamp` - Component showing message timestamp. | ||
| - `StickyHeader` - Component showing sticky header on the top of the `MessageList`/`Channel`. | ||
|
|
||
| ## Format Customization | ||
|
|
||
| The datetime format can be customized by providing date format through the `i18n` JSON. | ||
|
|
||
| ### Date & time formatting with i18n service | ||
|
|
||
| Formatting via i18n service allows for SDK wide configuration. The configuration is stored with other translations in JSON files. Formatting with i18n service has the following advantages: | ||
|
|
||
| - It is centralized. | ||
| - It takes into consideration the locale out of the box. | ||
| - Allows for high granularity - formatting per string, not component (opposed to props approach). | ||
| - Allows for high re-usability - apply the same configuration in multiple places via the same translation key. | ||
| - Allows for custom formatting logic. | ||
|
|
||
| The default datetime formatting configuration is stored in the JSON translation files. The default translation keys are namespaced with prefix `timestamp/` followed by the component name. For example, the message date formatting can be targeted via `timestamp/MessageTimestamp`, because the underlying component is called `MessageTimestamp`. | ||
|
|
||
| We can apply custom configuration in all the translation JSON files. It could look similar to the following example key-value pair. | ||
|
|
||
| ```json | ||
| "timestamp/SystemMessage": "{{ timestamp | timestampFormatter(format: YYYY) }}", | ||
| ``` | ||
|
|
||
| Besides overriding the formatting parameters above, we can customize the translation key via `timestampTranslationKey` prop. All the above components (`ChannelPreviewStatus`, `ImageGalleryHeader`, `InlineDateSeparator`, `MessageEditedTimestamp`, `MessageSystem`, `MessageTimestamp`, `StickyHeader`) accept this prop. | ||
|
|
||
| ```tsx | ||
| import { MessageTimestampProps, MessageTimestamp } from 'stream-chat-react-native'; | ||
|
|
||
| const CustomMessageTimestamp = (props: MessageTimestampProps) => ( | ||
| <MessageTimestamp {...props} timestampTranslationKey='customTimestampTranslationKey' /> | ||
| ); | ||
| ``` | ||
|
|
||
| ### Understanding the formatting syntax | ||
|
|
||
| Once the default prop values are nullified, we override the default formatting rules in the JSON translation value. We can take a look at an example: | ||
|
|
||
| ```json | ||
| "timestamp/MessageSystem": "{{ timestamp | timestampFormatter(calendar: true) }}", | ||
| ``` | ||
|
|
||
| or with custom calendar formats: | ||
|
|
||
| ```json | ||
| "timestamp/MessageSystem": "{{ timestamp | timestampFormatter(calendar: true; calendarFormats: {\"lastDay: \"[gestern um] LT\", \"lastWeek\": \"[letzten] dddd [um] LT\", \"nextDay\": \"[morgen um] LT\", \"nextWeek\": \"dddd [um] LT\", \"sameDay\": \"[heute um] LT\", \"sameElse\": \"L\"}) }}", | ||
| ``` | ||
|
|
||
| or with custom format: | ||
|
|
||
| ```json | ||
| "timestamp/MessageTimestamp": "{{ timestamp | timestampFormatter(format: LT) }}", | ||
| ``` | ||
|
|
||
| Let's dissect the example: | ||
|
|
||
| - The curly brackets (`{{`, `}}`) indicate the place where a value will be interpolated (inserted) into the string. | ||
| - Variable `timestamp` is the name of variable which value will be inserted into the string. | ||
| - The `|` character is a pipe that separates the variable from the formatting function. | ||
| - The `timestampFormatter` is the name of the formatting function that is used to convert the `timestamp` value into desired format | ||
| - The `timestampFormatter` can be passed the same parameters as the React components (`calendar`, `calendarFormats`, `format`) as if the function was called with these values. | ||
|
|
||
| **Params**: | ||
|
|
||
| - `calendar` - This is a boolean field to decide if the date format should be in calendar format or not. The default value is `false`. | ||
| - `calendarFormats` - This is an object that contains the formats for the calendar. The default value is `{ sameDay: 'LT', nextDay: 'LT', nextWeek: 'dddd', lastDay: 'dddd', lastWeek: 'dddd', sameElse: 'L' }`. | ||
| - `format` - This is a string that contains the format of the date. | ||
|
|
||
| If calendar formatting is enabled, the dates are formatted with time-relative words ("yesterday at ...", "last ..."). The calendar strings can be further customized with `calendarFormats` object. The `calendarFormats` object has to cover all the formatting cases as shows the example below: | ||
|
|
||
| ```js | ||
| { | ||
| lastDay: '[gestern um] LT', | ||
| lastWeek: '[letzten] dddd [um] LT', | ||
| nextDay: '[morgen um] LT', | ||
| nextWeek: 'dddd [um] LT', | ||
| sameDay: '[heute um] LT', | ||
| sameElse: 'L', | ||
| } | ||
| ``` | ||
|
|
||
| :::important | ||
| If any of the `calendarFormats` keys are missing, then the underlying library will fall back to hard-coded english equivalents | ||
| ::: | ||
|
|
||
| If `calendar` formatting is enabled, the `format` prop would be ignored. So to apply the `format` string, the `calendar` has to be disabled. | ||
|
|
||
| :::note | ||
| The described rules follow the formatting rules required by the i18n library used under the hood - `i18next`. You can learn more about the rules in [the formatting section of the `i18next` documentation](https://www.i18next.com/translation-function/formatting#basic-usage). | ||
| ::: | ||
|
|
||
| ### Custom datetime formatter functions | ||
|
|
||
| Besides overriding the configuration parameters, we can override the default `timestampFormatter` function by providing custom `Streami18n` instance: | ||
|
|
||
| ```tsx | ||
| import { Chat, Streami18n } from 'stream-chat-react-native'; | ||
|
|
||
| const chatClient = 'Your Chat client here'; | ||
|
|
||
| const i18n = new Streami18n({ | ||
| formatters: { | ||
| timestampFormatter: () => (val: string | Date) => { | ||
| return new Date(val).getTime() + ''; | ||
| }, | ||
| }, | ||
| }); | ||
|
|
||
| export const ChatApp = ({ apiKey, userId, userToken }) => { | ||
| return <Chat client={chatClient} i18nInstance={i18n}></Chat>; | ||
| }; | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.