Skip to content

Start to use CSS logical properties for docs pages #954

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 30, 2025

Conversation

mportiz08
Copy link
Contributor

Bug/issue #, if applicable:

Summary

This transition to logical properties and values (as opposed to physical/dimensional ones) will allow for UI elements and associated spacing to better accommodate languages with a right-to-left writing direction.

Although DocC doesn't yet support right-to-left localized content, this change will better future-proof the renderer if it does, allowing it to do things like flip the orientation of the sidebar and strings of text for languages that read from right to left instead of left to right.

Notes:

  • In some places like UI where code is displayed, we still want to render things as left-to-right regardless of the preferred locale, since this content is unlikely to be translated along with the documentation text.
  • This PR purposefully doesn't include any actual UI string translations for right-to-left languages yet—the Arabic example is provided for testing purposes only and contains no actual translated text.
  • This PR is limited to basic elements that would commonly be found on documentation pages and is not a complete audit of all relevant UI elements. This is meant to be a starting point and other kinds of content like tutorials would need similar changes in the future.

Testing

Test that UI elements are rendered differently in a rtl language

A new VUE_APP_DEFAULT_LOCALE=[locale] environment variable has been provided for configuring what is considered to be the "default" locale of the app instead of being hardcoded to "en-US". Note that this wouldn't necessarily ever need to be configured once DocC supports localization and allowing users to select alternate locales to browse documentation.

An empty strings file for the "ar" locale has been provided purely for testing purposes—it does not yet contain any actual translated strings.

  1. Configure VUE_APP_DEV_SERVER_PROXY with some documentation content and VUE_APP_DEFAULT_LOCALE=ar
  2. Run npm run serve
  3. Verify that UI elements in documentation pages flow from right-to-left where appropriate now (even if the content is still in English or falling back to the default UI strings)

Test that no spacing or visual regressions are introduced

  1. Run DocC-Render normally in the same manner as above without overriding VUE_APP_DEFAULT_LOCALE
  2. Verify that everything still renders as it did before with a left-to-right orientation

Checklist

Make sure you check off the following items. If they cannot be completed, provide a reason.

  • Added tests
  • Ran npm test, and it succeeded
  • Updated documentation if necessary

This transition to logical properties and values (as opposed to
physical/dimensional ones) will allow for UI elements and associated
spacing to better accomodate languages with a right-to-left writing
direction.

Although DocC doesn't yet support right-to-left localized content, this
change will better future-proof the renderer if it does, allowing it to
do things like flip the orientation of the sidebar and strings of text
for languages that read from right to left instead of left to right.

https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values
@mportiz08 mportiz08 requested a review from marinaaisa July 7, 2025 23:25
Copy link
Member

@marinaaisa marinaaisa left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've been testing the render using VUE_APP_DEFAULT_LOCALE and it's a great implementation.
It's super interesting how RTL languages transform the UI, very cool.

I left a minor comment but feel free to ignore it, it's not really relevant.
Thank you!

document.querySelector('html').setAttribute('lang', locale);
const htmlElement = document.querySelector('html');
htmlElement.setAttribute('lang', locale);
htmlElement.setAttribute('dir', getDirection(locale));
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My very minor suggestion is that we may want to cache the results of getDirection so we don't need to call the function every time that we update the locale.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the implementation of that function is just property lookups which don't really have any surprising performance impacts, so I'm not sure it's worth any added complexity for caching/memoization.

--scale-inline: 1;
}

html[dir="rtl"] {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Smart 👏

@mportiz08
Copy link
Contributor Author

@swift-ci test

@mportiz08 mportiz08 merged commit 77d966b into swiftlang:main Jul 30, 2025
1 check passed
@mportiz08 mportiz08 deleted the rtl/use-css-logical-properties branch July 30, 2025 22:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants