Skip to content

RTL & Internationalisation ​

RTL is not a feature bolted on at the end. Because AdminVora uses logical properties exclusively, it is a consequence of the architecture.


Enabling RTL ​

html
<html lang="ar" dir="rtl">

That is the entire requirement. No separate stylesheet, no class, no JavaScript.

js
AdminVora.theme.set('dir', 'rtl');
html
<button data-av-theme-set="dir:rtl">العربية</button>

Why it works: logical properties ​

Physical properties are banned in src/scss/. Enforced by stylelint-use-logical-spec.

Physical (banned)Logical (required)LTRRTL
margin-leftmargin-inline-startleftright
margin-rightmargin-inline-endrightleft
padding-leftpadding-inline-startleftright
border-leftborder-inline-startleftright
left: 0inset-inline-start: 0leftright
text-align: lefttext-align: startleftright
float: rightfloat: inline-endrightleft
widthinline-sizehorizontalhorizontal
heightblock-sizeverticalvertical
top: 0; bottom: 0inset-block: 0——
border-top-left-radiusborder-start-start-radiustop-lefttop-right
margin: 0 automargin-inline: auto——
scss
/* ❌ Breaks in RTL */
.av-menu__link {
  padding-left: 16px;
  border-left: 3px solid transparent;
  text-align: left;
}

/* ✅ Correct in both directions */
.av-menu__link {
  padding-inline-start: var(--av-space-4);
  border-inline-start: 3px solid transparent;
  text-align: start;
}

There is no RTL build ​

adminvora.rtl.css does not exist, and build:css emits one stylesheet plus its minified copy. Direction is a document attribute, not a build target:

html
<html dir="rtl">

That works because the stylesheet is written in logical properties throughout — margin-inline-start rather than margin-left, inset-inline-start rather than left — and npm run lint:css fails on a physical property, naming the logical form to use instead. Nothing is mirrored at build time because nothing needs to be.

The three properties with no logical form ​

transform, translate and clip-path have no direction-aware equivalent, so they are the one place a direction is written down. The rule is that the sign lives in a custom property, and one [dir="rtl"] rule flips it:

scss
.av-drawer               { --av-drawer-from: 100%; }
.av-drawer--start        { --av-drawer-from: -100%; }
[dir="rtl"] .av-drawer        { --av-drawer-from: -100%; }
[dir="rtl"] .av-drawer--start { --av-drawer-from: 100%; }

Seven such properties exist — --av-switch-travel, --av-drawer-from, --av-auth-slide, --av-chevron-nudge, --av-progress-flow, --av-quick-shift and --av-menu-sweep — and a directional-transform lint rule fails any rule that declares a transform under [dir] while hard-coding the sign inline. The gate exists because this is the one class of RTL bug that logical properties cannot catch for you.

Because the direction is never baked into the file you loaded, a runtime dir toggle works: set the attribute and the interface flips, with no second request and no reload.


What still needs manual attention ​

Logical properties handle ~95%. These are the exceptions.

Icons that must mirror ​

scss
[dir="rtl"] .av-icon--flip { transform: scaleX(-1); }

See Iconography for the mirror/no-mirror list.

Transforms and translations ​

translate is physical. Sidebars must flip explicitly.

scss
.av-sidebar { translate: -100% 0; }
[dir="rtl"] .av-sidebar { translate: 100% 0; }

/* Or, better, use a logical custom property */
.av-sidebar { --av-slide: -100%; translate: var(--av-slide) 0; }
[dir="rtl"] .av-sidebar { --av-slide: 100%; }

Gradients ​

scss
/* Physical direction */
.av-hero { background: linear-gradient(to right, var(--av-primary-500), var(--av-accent-500)); }

/* Direction-aware */
.av-hero { background: linear-gradient(to var(--av-grad-dir, right), …); }
[dir="rtl"] { --av-grad-dir: left; }

Box shadows with a horizontal offset ​

scss
.av-drawer { box-shadow: -8px 0 24px oklch(0% 0 0 / .12); }
[dir="rtl"] .av-drawer { box-shadow: 8px 0 24px oklch(0% 0 0 / .12); }

Charts ​

ApexCharts draws SVG and does not respect dir, and the runtime does not mirror charts. The chart options schema has no setting for it either, so adjust the instance once it is ready:

js
AdminVora.on('av:chart:ready', ({ chart }) => {
  if (document.documentElement.dir === 'rtl') {
    chart.updateOptions({ yaxis: { opposite: true }, legend: { horizontalAlign: 'left' } });
  }
});

Numbers and dates ​

Numbers are always LTR, even in an RTL sentence. Browsers handle this via the Unicode bidirectional algorithm, but isolated numeric spans need help:

html
<span dir="ltr" style="font-family: var(--av-font-mono)">+353 1 234 5678</span>
<bdi>{{ user.name }}</bdi>

<bdi> (bidirectional isolate) prevents a user-supplied Arabic name from reordering the surrounding English UI text — a real bug that shows up in comment threads and user lists.

Directional wording ​

scss
/* ❌ Physical language in a class name */
.av-drawer--left { }

/* ✅ Logical */
.av-drawer--start { }
.av-drawer--end { }

Testing RTL ​

js
// tests/visual/rtl.spec.js
const PAGES = ['/dashboard', '/orders', '/settings', '/apps/mail'];

for (const path of PAGES) {
  test(`${path} — RTL`, async ({ page }) => {
    await page.goto(path);
    await page.evaluate(() => document.documentElement.setAttribute('dir', 'rtl'));
    await expect(page).toHaveScreenshot(`${path.replace(/\//g, '_')}-rtl.png`);
  });
}

test('no physical properties in computed styles that break RTL', async ({ page }) => {
  await page.goto('/dashboard');
  await page.evaluate(() => document.documentElement.setAttribute('dir', 'rtl'));

  // Sidebar must be on the right in RTL
  const box = await page.locator('.av-sidebar').boundingBox();
  const vw = page.viewportSize().width;
  expect(box.x).toBeGreaterThan(vw / 2);
});

Manual check with a keyboard-only pass — Tab order must still be visually left-to-right within a row of buttons that reads right-to-left. This is browser behaviour and usually correct, but custom roving-tabindex implementations get it wrong.


Internationalisation ​

AdminVora ships English strings only.

There is no translation layer. The runtime reads no locale configuration and has no t() helper; the few strings it writes itself — a grid's count, a validation message, a toast after a bulk action — are English literals in src/js/adminvora.js. Everything else a reader sees is your own server-rendered markup, which your framework already translates.

Money is the exception that is locale-aware: AdminVora.utils.formatCurrency(amount, currency, locale) formats through Intl.NumberFormat. For numbers and dates in your own code, use Intl directly — never string concatenation.

Direction is fully supported: set dir on <html> and the stylesheet follows, because it is written in logical properties throughout. See Enabling RTL above.


RTL languages and their quirks ​

LanguageCodeNotes
ArabicarContextual letterforms; test with a real Arabic font, not a Latin fallback. Numerals may be Eastern Arabic (٠١٢) — controlled by font-feature-settings: 'anum' or the locale.
HebrewheNo contextual forms; simpler. Fewer font options — Noto Sans Hebrew is the safe choice.
Persian / FarsifaArabic script plus four extra letters. Persian uses ۰۱۲ numerals by default.
UrduurNastaliq style needs much greater line height (2.0+) or descenders clip.
scss
:lang(ur) { line-height: 2; }
:lang(ar), :lang(fa) { font-family: 'NotoSansArabic', var(--av-font-sans); }

Fonts for RTL scripts ​

Add a face with a disjoint unicode-range so Latin users never download it — see Typography.

scss
@font-face {
  font-family: 'InterVariable';                       /* same family name */
  src: url('../fonts/noto-arabic-var.woff2') format('woff2-variations');
  unicode-range: U+0600-06FF, U+0750-077F, U+08A0-08FF, U+FB50-FDFF, U+FE70-FEFF;
  font-weight: 100 900;
  font-display: swap;
}

RTL checklist ​

  • [ ] dir="rtl" on <html>, not on <body>
  • [ ] lang attribute matches the content language
  • [ ] No physical properties in your own CSS (npm run lint:css catches these)
  • [ ] Directional icons carry av-icon--flip
  • [ ] Sidebar, drawer, and toast slide from the correct edge
  • [ ] Charts configured with opposite: true on the y-axis
  • [ ] Phone numbers, IBANs, and codes wrapped in dir="ltr"
  • [ ] User-generated names wrapped in <bdi>
  • [ ] Date pickers and calendars given the locale
  • [ ] Visual snapshots exist for RTL on every page
  • [ ] Keyboard tab order verified manually
  • [ ] Tested with real Arabic/Hebrew content, not Latin placeholder text

Warning — testing RTL with English text (dir="rtl" on Latin content) catches layout bugs but misses text-rendering and line-breaking bugs. Use real content for the final pass.

Read next: The Customizer.

Documentation for @creativeigniter/adminvora