docs: rtl date time format blog #7936
Conversation
|
|
||
| To format the segments according to the user locale, we rely on the browser’s [Unicode Bidirectional Algorithm](https://unicode.org/reports/tr9/). However, we found that some of our CSS styles were interferring with algorithm's application, leading to incorrect formating. For instance, in `he-IL`, the proper numeric date format should be `DD.MM.YYYY`, but our date component was displaying `YYYY.MM.DD`. This issue varied across different RTL languages for date fields, but for time fields, we observed a consistent problem across all RTL languages where time segments were flipped, rendering `MM:HH` instead of the correct `HH:MM` format. | ||
|
|
||
| <RTLTimefield /> |
There was a problem hiding this comment.
i have some things i'd like to fix this image so it'll get eventually get replaced but the jist is there. wanted to have something so people could see how the blog flows with this image
|
|
||
| While it seemed like a relatively simple fix, we later discovered through testing that this only corrected the format when segments contained actual values. If they had placeholder values, the order was still incorrect, causing some undesirable behaviors. It seemed that the Unicode Bidirectional Algorithm was interpreting placeholder values differently from actual values. As a result, when a segment was cleared back to its placeholder, it would shift back to the incorrect order. And then when a user entered a value, the segment would shift back to its correct order. Our challenge was to ensure consistent formatting regardless of whether a segment contained a placeholder or user-entered value — all without hard coding segment order for each locale. | ||
|
|
||
| <Video src={placeholderVideoURL} loop autoPlay muted /> |
There was a problem hiding this comment.
Might just be me, but I kinda found it hard to notice what this video was illustrating due to my unfamiliarity with the numerals here. Maybe an annotated before and after image would be more helpful?
There was a problem hiding this comment.
ah yeah i can see how that's confusing. i wanted the video to showcase how it's confusing for the segments to shift around but maybe i can also insert images as well that are annotated to explain. i'll play around with it a bit
There was a problem hiding this comment.
I think we should make the videos not loop and not autoplay, and just give the user play controls. It's hard to see where the video begins and ends so a bit challenging to tell what's happening.
|
|
||
| <Video src={keyboardVideoURL} loop autoPlay muted /> | ||
|
|
||
| As a result, we updated the keyboard navigation in right-to-left langauges to rely on the positioning of the different segments to determine which node to receive focus for an intuitive keyboard experience. |
There was a problem hiding this comment.
I'm not entirely sure what this fix entails, mind clarifying?
There was a problem hiding this comment.
This is a great deep dive! I wonder if it might help to have a short section at the start that gives a high level overview of RTL languages and how support for it is commonly implemented (mirroring, bidirectional text with mixed rtl/ltr, etc). I have a feeling that most developers are not familiar with it, and we get pretty deep into the weeds very quickly here, so we might need to explain some stuff more. Then later on, don't assume devs know what <bdo> is, what these different unicode control characters are, etc. The links are helpful, but most people won't click them so we might need just a bit more explanation of our own.
|
|
||
| ## Unicode Bidirectional Algorithm | ||
|
|
||
| To format the segments according to the user locale, we rely on the browser’s [Unicode Bidirectional Algorithm](https://unicode.org/reports/tr9/). However, we found that some of our CSS styles were interfering with the algorithm's application, leading to incorrect formatting. For instance, in Hebrew (`he-IL`), the proper numeric date format should be `DD.MM.YYYY`, but our date component was displaying `YYYY.MM.DD`. This issue varied across different RTL languages for date fields, but for time fields, we observed a consistent problem across all RTL languages where time segments were flipped, rendering `MM:HH` instead of the correct `HH:MM` format. |
There was a problem hiding this comment.
Previous to the change, I wouldn't say we were relying on the unicode bidi algorithm, we were relying on flex box. Maybe it would make sense to say we rely on the browsers Intl.DateTimeFormat API and then introduce the bidi algorithm later when you talk about the fix?
|
|
||
| <RTLTimefield /> | ||
|
|
||
| We found the culprit to be two things. First, we were applying `display: flex` on the container wrapping the segments. Second, each segment was being rendered as a `div` with `display: block`. Instead, we needed to use [normal CSS flow layout](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_display/Flow_layout) on the wrapper around the segments and update each segment to be a span instead. |
There was a problem hiding this comment.
Maybe add something like this after the sentence about flex?
Usually, this is the correct way to handle right-to-left layout since it automatically mirrors in those languages. However, in this case, the segments are not strictly right-to-left or left-to-right: they are a mix.
I think the display: block issue is really more of a side effect of the change to using flow layout. When we used flex this didn't matter, but it did once we used flow layout. Probably less important to mention than the flex part.
At the end of the paragraph seems like a good point to introduce Unicode bidi.
Instead, we needed to use normal CSS flow layout on the wrapper around the segments, an update each segment to be a span instead of a div. This allows the browser to apply the Unicode Bidirectional Algorithm, which reorders the characters in right-to-left text according to a set of standardized rules.
|
|
||
| We found the culprit to be two things. First, we were applying `display: flex` on the container wrapping the segments. Second, each segment was being rendered as a `div` with `display: block`. Instead, we needed to use [normal CSS flow layout](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_display/Flow_layout) on the wrapper around the segments and update each segment to be a span instead. | ||
|
|
||
| While it seemed like a relatively simple fix, we later discovered through testing that this only corrected the format when segments contained actual values. If they had placeholder values, the order was still incorrect, causing some undesirable behaviors. It seemed that the Unicode Bidirectional Algorithm was interpreting placeholder values differently from actual values. As a result, when a segment was cleared back to its placeholder, it would shift back to the incorrect order. Furthermore, when a user entered a value, the segment would shift back to its correct order. This posed an interesting challenge: how do we ensure consistent formatting regardless of whether a segment contained a placeholder or a user-entered value — all without hard coding segment order for each locale? |
There was a problem hiding this comment.
| While it seemed like a relatively simple fix, we later discovered through testing that this only corrected the format when segments contained actual values. If they had placeholder values, the order was still incorrect, causing some undesirable behaviors. It seemed that the Unicode Bidirectional Algorithm was interpreting placeholder values differently from actual values. As a result, when a segment was cleared back to its placeholder, it would shift back to the incorrect order. Furthermore, when a user entered a value, the segment would shift back to its correct order. This posed an interesting challenge: how do we ensure consistent formatting regardless of whether a segment contained a placeholder or a user-entered value — all without hard coding segment order for each locale? | |
| While it seemed like a relatively simple fix, we later discovered through testing that this only corrected the format when segments contained numeric values. If they had placeholder values, the order was still incorrect, causing some undesirable behaviors. This was because the placeholders are typically non-numeric characters, e.g. `'شهر'` representing "month" in Arabic. As a result, when the user pressed the Backspace key to clear a segment to its placeholder, the order of the segments would change. Furthermore, when a user entered a value, the segment would shift back to its correct order. This posed an interesting challenge: how do we ensure consistent formatting regardless of whether a segment contained a placeholder or a user-entered value — all without hard coding segment order for each locale? |
|
|
||
| While it seemed like a relatively simple fix, we later discovered through testing that this only corrected the format when segments contained actual values. If they had placeholder values, the order was still incorrect, causing some undesirable behaviors. It seemed that the Unicode Bidirectional Algorithm was interpreting placeholder values differently from actual values. As a result, when a segment was cleared back to its placeholder, it would shift back to the incorrect order. And then when a user entered a value, the segment would shift back to its correct order. Our challenge was to ensure consistent formatting regardless of whether a segment contained a placeholder or user-entered value — all without hard coding segment order for each locale. | ||
|
|
||
| <Video src={placeholderVideoURL} loop autoPlay muted /> |
There was a problem hiding this comment.
I think we should make the videos not loop and not autoplay, and just give the user play controls. It's hard to see where the video begins and ends so a bit challenging to tell what's happening.
|
|
||
| We first addressed time fields since they were easier to fix. As mentioned earlier, the segments in time fields for RTL languages were flipped. We learned, however, that regardless of locale, all time fields should follow the `HH:MM` format. Knowing this, we could apply a direction of left-to-right (LTR) on the numeric values across all segments in a time field. | ||
|
|
||
| Instead of wrapping the the segments in a `<bdo>` tag with a `dir=“ltr”` which would impact the DOM structure and have potentially introduce side effects, we chose to use the [LRI (left-to-right isolate) Unicode character](https://www.w3.org/International/questions/qa-bidi-unicode-controls) to encapsulate the time segments and force an LTR direction. Adding this Unicode character is the equivalent of wrapping the time segments in a `<bdo>` tag but offers several advantages. Since the character is invisible, there are no visual changes, and by adding it as a siblings to the segments, we avoided major structural changes to the DOM. Additionally, by enforcing a LTR direction, we no longer had to worry about whether the time field consisted of placeholders or actual values. Lastly, it ensured that when a date field included a time, that the time field appeared in the correct order with respect to the date field (e.g. `8:45 1/31/2025` instead of `1/31/2025 8:45`). |
There was a problem hiding this comment.
Link to bdo on MDN? I bet most developers haven't used it
| </div> | ||
| ``` | ||
|
|
||
| Through much trial and error, we discovered that appplying the [left-to-right embedding (LRE) Unicode](https://unicode.org/reports/tr9/#Explicit_Directional_Embeddings) on the date segments allowed us to to treat the text as embedded left-to-right while preserving the right-to-left mark on the separators, ensuring that Arabic dates display in the correct format. While we could have added Unicode to the segments like we did with the time fields, we opted for the [equivalent CSS](https://unicode.org/reports/tr9/#Markup_And_Formatting) approach instead to avoid modifying the DOM. This CSS is applied on date segments with placeholder or actual values to avoid the behavior discussed earlier with shifting segments. Through additional testing, we found that we should only apply left-to-right embedding on numeric values. If the value was displayed as text (e.g. "November" instead of "11") we did not apply this CSS. |
There was a problem hiding this comment.
We might need to show how it was rendering in the incorrect cases again here. I lost track of which problem this was solving when reading it. If I remember correctly it was so that the segments were ordered in LTR but the contents of the individual segments were RTL (so as not to mess up the placeholder text)?
|
|
||
| As you can see, formatting dates correctly is quite challenging, especially in right-to-left languages. Fortunately, tools like the Unicode Bidirectional Algorithm help with formatting so we don’t have to handle everything manually. However, as we discovered with this bug, it doesn’t always work as expected and unexpected factors can interfere with it. | ||
|
|
||
| After extensive testing, we developed a solution that ensures proper formatting for users of React Spectrum, React Aria Components, and our hooks. If you haven’t tried our date and time components yet, we encourage you to check them out! And if you’re already using them, be sure to update to at least version ^3.40 to ensure correct formatting in right-to-left languages and to make the appropriate changes noted in the [release notes](https://react-spectrum.adobe.com/releases/2025-03-05.html#date-and-time-formatting-in-rtl-languages)! |
There was a problem hiding this comment.
3.40 only applies to RSP. Maybe just say the March 2025 release?
Closes
✅ Pull Request Checklist:
📝 Test Instructions:
🧢 Your Project: