RTL Languages Support #6138

AhmedBaset · 2023-07-07T20:42:57Z

This PR addresses right-to-left (RTL) languages styles, directionality, and other relevant adjustments for the React documentation.

Types of changes

Updated tailwindcss to the latest version to utilize logical properties.
Added the .isRTL property to the siteConfig object ^{note 1}.
Set the dir attribute on the <html> element to either ltr or rtl based on the isRTL property.
Maintained the dir attributes of <InlineCode />, <CodeBlock />, and <Sandpack /> as ltr regardless of the isRTL property.
Converted physical and directional properties to logical properties ^{+96% of browsers support logical properties}:
- Replaced pl-*, pr-*, ml-*, and mr-* with ps-*, pe-*, ms-*, and me-*.
- Replaced text-left and text-right with text-start and text-end.
- Replaced left-* and right-* with start-* and end-*.
- Replaced rounded-l-* and rounded-r-* with rounded-s-* and rounded-e-*.
- Replaced border-l-* and border-r-* with border-s-* and border-e-*.
- And so on.
For the components <IconNavArrow />, <IconArrow />, <IconArrowSmall />, and <IconChevron />, added two additional values to the displayDirection prop: start and end. These values behave differently based on the page direction and should be used instead of left and right values ^{note 2}.
This PR does not affect anything in LTR languages.

Live demo:

See this live demo of the documentation with some Arabic data (from ar.react.dev)

Notes:

Note 1: The `.isRTL` property

We had several options to choose from:

Added a new property to the siteConfig object and set it manually for each language.

exports.siteConfig = {
  // ...
  languageCode: 'ar',
  isRTL: true,
  // ...
};

Used language detection like rtl-detect to automatically detect the language direction and set the property.

const siteConfig = {
  // ...
  languageCode: 'ar',
  hasLegacySite: true,
  isRTL: false, // Do NOT ever set this to true. It is deprecated.
  // ...
};

const rtlDetect = require('rtl-detect');
siteConfig.isRTL = rtlDetect.isRtlLang(siteConfig.languageCode);

exports.siteConfig = siteConfig;

Note 2: New values for the displayDirection prop

export const IconNavArrow = memo<
  JSX.IntrinsicElements['svg'] & {
    /**
     * The direction the arrow should point.
     * `start` and `end` are relative to the current locale.
     * For example, in LTR, `start` is left and `end` is right.
     */
    displayDirection: 'start' | 'end' | 'right' | 'left' | 'down';
  }
>(function IconNavArrow({displayDirection = 'end', className}) {
  const classes = cn(
    'duration-100 ease-in transition',
    {
      'rotate-0': displayDirection === 'down',
      'rotate-90': displayDirection === 'left',
      '-rotate-90': displayDirection === 'right',
      'rotate-90 rtl:-rotate-90': displayDirection === 'start',
      '-rotate-90 rtl:rotate-90': displayDirection === 'end',
    },
    className
  );

  return (
    <svg
      // ...
      className={classes}
      //...
  );
});

@gaearon, @rickhanlonii, @acdlite, and React Community, could you please review this PR?

1- Update TailwindCSS to use the logical properities such as `ps-1` instead of `pl-1`. there are logical properities for margin, padding, inset, and text direction. 2- Install `rtl-detect` detect if the language is RTL direction. Note: this might be uninstalled if we use the manual way to specify rtl language.

instead of directions properties (e.g. `pr-0` to `pe-0`)

…properties." This reverts commit df9620d.

…element

…me languages

AhmedBaset · 2023-08-09T20:15:07Z

@lunaleaps and @mattcarrollcode, could you please review this? As Arabic users, we have difficulties reading the Arabic docs with LTR directions.

src/components/Icon/IconChevron.tsx

src/components/Layout/HomeContent.js

lunaleaps

Changes look good to me! Just a couple small q's about alt properties and a CSS clarification.

Thanks for doing this work!

Question - is there a lint we can set up to ensure we don't start re-introducing left/right css properties?

lunaleaps · 2023-08-11T16:32:20Z

Thanks for addressing, looks like just conflicting files and then I can merge!

AhmedBaset · 2023-08-11T17:21:51Z

Thanks for addressing, looks like just conflicting files and then I can merge!

Resolved

rickhanlonii · 2023-08-11T19:42:28Z

Wow this is awesome, thanks a ton for all that went into this!

Nabeel20 · 2023-08-12T13:30:05Z

This is amazing, thanks 🙏🏻

* fix: wronge styles when applying RTL it was `top-0 left-0 ...` by wrong I made it `inset-x-0`. * fix wrong styles * fix wrong styles * style canary icon with RTL-friendly styles * chore: utilize mx-* instead of me-* & ms-* * utilize relative styles * chore: use mx-* instead of me-* & ms-* * style canary icon with RTL-frindly styles * Update OpenInTypeScriptPlayground.tsx

AhmedBaset · 2023-08-28T22:21:57Z

@lunaleaps: Question: Is there a lint we can set up to ensure we don't start re-introducing left/right CSS properties?

Regarding icons, we can eliminate the "left" and "right" in displayDirection to enforce future updates to employ "start" and "end" directions.

For Tailwindcss classes, I have released eslint-plugin-rtl-friendly to serve this purpose. It reports in cases where you utilize physical properties like pl-*, prompting you to use ps-* instead, with auto-fix by eslint --fix

Note: Up til now, It doesn't detect like className={cn(...)}. It works only for string up to this moment v.0.1.0 and doesn't lint eslint file (StyleLint is needed for that).

We have the option to install and extend it. By configuring no-physical-properties as error (while the default "recommended config" is "warn") to enhance strictness.

What do you think? @lunaleaps @rickhanlonii

lunaleaps · 2023-08-29T15:58:23Z

Thanks @A7med3bdulBaset for looking into that! I'm curious if we do still need some left/right properties and how we exclude them from the lint? Otherwise, this looks like a great idea!

AhmedBaset · 2023-08-29T16:46:28Z

Thanks @A7med3bdulBaset for looking into that! I'm curious if we do still need some left/right properties and how we exclude them from the lint? Otherwise, this looks like a great idea!

Could you provide an example of left/right properties we need where start/end wouldn't resolve the issue?

A: There are NONE.

The only places we seem to need them are in the <CodeBlock />, <Sandbox/>, and similar components. However, even in those cases, we use dir="ltr", so ps-* becomes pl-*, regardless of the page direction.

AhmedBaset added 30 commits July 5, 2023 17:21

add siteConfig.isRTL

1c54126

add dir attribute to the root element

df06f56

edit some tw classes to utilize logical properties

12b1972

instead of directions properties (e.g. `pr-0` to `pe-0`)

edit some tw classes to utilize logical properties

4206637

instead of directions properties (e.g. `pr-0` to `pe-0`)

edit some tw classes to utilize logical properties

313e3f9

instead of directions properties (e.g. `pr-0` to `pe-0`)

edit some tw classes to utilize logical properties

68e79f1

instead of directions properties (e.g. `pr-0` to `pe-0`)

Refactor TW classes: Use logical properties over directional properties.

df9620d

Revert "Refactor TW classes: Use logical properties over directional …

b597018

…properties." This reverts commit df9620d.

Refactor TW classes: Use logical properties over directional properties.

0ab127d

Refactor TW classes: Use logical properties over directional properties.

18036cc

Refactor TW classes: Use logical properties over directional properties.

54b3f06

Add start and end directions to the IconNavArrow

1fa7d3d

Add Note about isRTL prop

7e68277

Refactor TW classes: Use logical properties over directional properties.

06ee992

Refactor TW classes: Use logical properties over directional properties.

96b5852

Refactor TW classes: use logical properties over directional properties

f618f6b

Refactor TW classes: use logical properties over directional properties

414b0bf

Refactor TW classes: use logical properties over directional properties

f455260

set dir attr of CodeBlock to ltr even the page dir is rtl

6a45e88

Refactor TW classes: use logical properties over directional properties

9f6ef2c

Refactor TW classes: use logical properties over directional properties

9204cec

Add start and end directions to some icons

1411c3a

Refactor TW classes: use logical properties over directional properties

0a3456c

Refactor TW classes: use logical properties over directional properties

3585846

Refactor TW classes: use logical properties over directional properties

486fee5

Refactor TW classes: use logical properties over directional properties

4402f0e

set dir attr of ConsoleBlock to ltr to overwrite the dir of root …

d40e5ec

…element

Refactor TW classes: use logical properties over directional properties

b4c17d0

set dir=ltr on inline code blocks to overwrite <html dir="rtl"> in so…

808f69b

…me languages

vercel bot deployed to Preview July 25, 2023 05:12 View deployment

AhmedBaset mentioned this pull request Aug 2, 2023

translating HomeContent.js reactjs/ar.react.dev#514

Closed

rebase with the main branch

5c37d14

vercel bot deployed to Preview August 9, 2023 20:20 View deployment

lunaleaps reviewed Aug 10, 2023

View reviewed changes

src/components/Icon/IconChevron.tsx Outdated Show resolved Hide resolved

lunaleaps reviewed Aug 10, 2023

View reviewed changes

src/components/Layout/HomeContent.js Outdated Show resolved Hide resolved

lunaleaps reviewed Aug 10, 2023

View reviewed changes

src/components/Layout/HomeContent.js Outdated Show resolved Hide resolved

lunaleaps approved these changes Aug 10, 2023

View reviewed changes

remove unnecessary alt

d572659

vercel bot deployed to Preview August 10, 2023 22:23 View deployment

add start & end display directions to the Chevron Icon

298c98f

vercel bot deployed to Preview August 10, 2023 22:48 View deployment

rebase with the main branch

ad4ddca

vercel bot deployed to Preview August 11, 2023 17:14 View deployment

Merge branch 'main' into rtl-handling

f13eddb

vercel bot deployed to Preview August 11, 2023 17:17 View deployment

rickhanlonii merged commit 819518c into reactjs:main Aug 11, 2023
4 checks passed

This was referenced Aug 14, 2023

Annex to #6138 #6226

Merged

New Arabic Translation Progress reactjs/ar.react.dev#464

Open

NGHdeveloper mentioned this pull request Aug 15, 2023

RTL Languages Support #6138, generates an error #6231

Open

zadokdaniel mentioned this pull request Sep 5, 2023

Offering Assistance with React Documentation Translation to Hebrew reactjs/he.react.dev#323

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

RTL Languages Support #6138

RTL Languages Support #6138

AhmedBaset commented Jul 7, 2023 •

edited

AhmedBaset commented Aug 9, 2023

lunaleaps left a comment

lunaleaps commented Aug 11, 2023

AhmedBaset commented Aug 11, 2023

rickhanlonii commented Aug 11, 2023

Nabeel20 commented Aug 12, 2023

AhmedBaset commented Aug 28, 2023

lunaleaps commented Aug 29, 2023

AhmedBaset commented Aug 29, 2023

RTL Languages Support #6138

RTL Languages Support #6138

Conversation

AhmedBaset commented Jul 7, 2023 • edited

Types of changes

Live demo:

Notes:

AhmedBaset commented Aug 9, 2023

lunaleaps left a comment

Choose a reason for hiding this comment

lunaleaps commented Aug 11, 2023

AhmedBaset commented Aug 11, 2023

rickhanlonii commented Aug 11, 2023

Nabeel20 commented Aug 12, 2023

AhmedBaset commented Aug 28, 2023

lunaleaps commented Aug 29, 2023

AhmedBaset commented Aug 29, 2023

AhmedBaset commented Jul 7, 2023 •

edited