Use CSS Logical Properties for RTL and LTR Internationalization in WordPress

Home » CSS » Use CSS Logical Properties for RTL and LTR Internationalization in WordPress
November 5, 2023 CSS
Use CSS Logical Properties for RTL and LTR Internationalization in WordPress

CSS logical properties replace physical direction terms (left, right, top, bottom) with writing-mode-relative terms (inline-start, inline-end, block-start, block-end) — enabling a single CSS ruleset to handle both LTR (left-to-right) languages like English and RTL (right-to-left) languages like Arabic, Hebrew, and Persian without any JavaScript toggling, duplicated stylesheets, or [dir="rtl"] selectors. Physical properties are tied to the viewport: margin-left always means the left side of the screen regardless of text direction. Logical properties are tied to the flow of text: margin-inline-start means the start of the inline axis — which is the left side for LTR and the right side for RTL — so one declaration covers both. The logical property equivalents map as follows: margin-left → margin-inline-start, margin-right → margin-inline-end, padding-top → padding-block-start, padding-bottom → padding-block-end, width → inline-size, height → block-size, border-left → border-inline-start, text-align: left → text-align: start. Shorthand logical properties collapse the four sides: margin-inline: 1rem sets both margin-inline-start and margin-inline-end to 1rem, equivalent to margin: 0 1rem but direction-aware; padding-block: 2rem 1rem sets block-start to 2rem and block-end to 1rem. WordPress core has been migrating its admin CSS to logical properties since WordPress 6.1 as part of its RTL improvement initiative. For WordPress themes that need to support Arabic or Hebrew audiences (significant global markets), adopting logical properties eliminates the need for separate RTL stylesheets and the /* rtl:ignore */ comments used by the rtlcss tool. Browser support for CSS logical properties is excellent — all modern browsers including Safari 15+ support the full set. The CSS custom properties post covers design tokens; logical properties ensure those tokens apply correctly across writing directions.

Problem: A WordPress theme supports both English and Arabic content — the current CSS uses physical properties (margin-left, text-align: left, border-left) throughout, requiring a separate rtl.css file that mirrors the entire stylesheet with left/right values swapped. Any CSS change must be duplicated in the RTL file, causing frequent inconsistencies.

Solution: Replace physical direction properties with CSS logical properties throughout the theme — one stylesheet automatically renders correctly for both LTR English and RTL Arabic without any additional files or direction-specific overrides.

/* ── Before: physical properties (requires duplicate RTL stylesheet) ──────── */
.card {
    margin-left:   1.5rem;
    padding-left:  1.25rem;
    border-left:   4px solid var(--color-primary);
    text-align:    left;
    width:         300px;
    height:        auto;
}

.card__icon {
    float:         left;
    margin-right:  0.75rem;
}

.nav__arrow {
    background-image: url('arrow-right.svg');
}

/* ── After: logical properties (single stylesheet, RTL-aware) ─────────────── */
.card {
    margin-inline-start:  1.5rem;       /* was margin-left  */
    padding-inline-start: 1.25rem;      /* was padding-left */
    border-inline-start:  4px solid var(--color-primary); /* was border-left */
    text-align:           start;        /* was text-align: left */
    inline-size:          300px;        /* was width */
    block-size:           auto;         /* was height */
}

.card__icon {
    float:               inline-start;  /* was float: left */
    margin-inline-end:   0.75rem;       /* was margin-right */
}

/* For directional icons that must mirror, use CSS logical + content direction */
.nav__arrow {
    background-image: url('arrow-right.svg');
}
[dir="rtl"] .nav__arrow {
    /* Only for decorative SVGs that cannot be expressed logically */
    transform: scaleX(-1);
}

/* ── Shorthand logical properties ─────────────────────────────────────────── */
.section {
    /* Sets block-start: 4rem, block-end: 2rem */
    padding-block: 4rem 2rem;

    /* Sets inline-start AND inline-end to auto (horizontal centering) */
    margin-inline: auto;

    /* Sets max-width equivalent */
    max-inline-size: 72rem;
}

/* ── Border-radius logical properties ─────────────────────────────────────── */
.tag {
    /* Top-left corner in LTR, top-right corner in RTL */
    border-start-start-radius: 0.5rem;
    /* Top-right corner in LTR, top-left corner in RTL */
    border-start-end-radius:   0.5rem;
    border-end-start-radius:   0;
    border-end-end-radius:     0;
}

/* ── Inset logical properties (position) ──────────────────────────────────── */
.tooltip {
    position: absolute;
    /* was: top: 0; left: 0; */
    inset-block-start:  0;
    inset-inline-start: 0;

    /* Shorthand: inset: block-start block-end inline-start inline-end */
    /* Or: inset-block: 0 auto; inset-inline: 0 auto; */
}

NOTE: The CSS logical property for border-radius corners uses a two-word naming convention that is easy to mix up: border-start-start-radius means block-start (top) + inline-start (left in LTR) — the top-left corner in LTR, the top-right in RTL. The physical equivalent is border-top-left-radius. The pattern is always border-{block-direction}-{inline-direction}-radius. When retrofitting an existing theme, run the rtlcss tool in analysis mode first — it identifies which properties would be flipped for RTL and flags the ones that need manual review (such as decorative background images and transformed SVGs that cannot be expressed with logical properties alone).

Related posts