arabic-rtl-best-practices

阿拉伯语 RTL 最佳实践

说明

步骤 1：设置文档方向

始终从 HTML 属性开始（而不只是 CSS）：

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

这会告知浏览器、屏幕阅读器和 CSS 使用 RTL 作为基础方向。

步骤 2：使用 CSS 逻辑属性

布局中绝不要使用物理方向属性：

物理属性（避免使用）	逻辑属性（使用）
margin-left	margin-inline-start
margin-right	margin-inline-end
padding-left	padding-inline-start
padding-right	padding-inline-end
border-left	border-inline-start
text-align: left	text-align: start
text-align: right	text-align: end
float: left	float: inline-start
left: 10px	inset-inline-start: 10px

这样布局就会在 RTL 模式下自动镜像。

步骤 3：处理双向文本

混排阿拉伯语和英语／数字时：

/* Isolate embedded LTR content */
.ltr-content {
  unicode-bidi: isolate;
  direction: ltr;
}

/* For inline elements with mixed content */
.bidi-override {
  unicode-bidi: bidi-override;
}

常见的双向文本问题：

• 电话号码显示顺序颠倒：用 <bdo dir="ltr"> 包裹
• 标点出现在句子错误的一端：使用 unicode-bidi: isolate
• 阿拉伯语文本中的 URL／电子邮件地址：用 <span dir="ltr"> 包裹

步骤 4：阿拉伯语排版

推荐的字体栈：

font-family: 'Tajawal', 'Assistant', 'Rubik', 'Noto Sans Arabic', sans-serif;

排版设置：

body[dir="rtl"] {
  font-size: 16px; /* Arabic needs slightly larger than Latin */
  line-height: 1.7;
  letter-spacing: normal; /* NEVER add letter-spacing for Arabic */
  word-spacing: 0.05em; /* Slight word spacing improves readability */
}

步骤 5：特定框架的设置

Tailwind CSS RTL（v3.3+ / v4）：

优先使用逻辑属性工具类，而不是 rtl:／ltr: 变体：

物理类	逻辑类	CSS 属性
ml-4	ms-4	margin-inline-start
mr-4	me-4	margin-inline-end
pl-4	ps-4	padding-inline-start
pr-4	pe-4	padding-inline-end
left-4	start-4	inset-inline-start
right-4	end-4	inset-inline-end
rounded-l-lg	rounded-s-lg	border-start-start-radius + border-end-start-radius
rounded-r-lg	rounded-e-lg	border-start-end-radius + border-end-end-radius

<div class="ltr:ml-4 rtl:mr-4">...</div>


<div class="ms-4">...</div>

仅在逻辑属性无法处理的情况下（例如方向性图标、变换）使用 rtl:／ltr: 变体。

Tailwind v4 注意事项： v4 使用 CSS 优先的配置方式（在 CSS 中使用 @import "tailwindcss"），而不是 tailwind.config.js。逻辑工具类在 v3 和 v4 中的用法相同。

Next.js App Router：

// app/layout.tsx
import { Tajawal } from 'next/font/google';

const tajawal = Tajawal({
  subsets: ['arabic', 'latin'],
  weight: ['400', '500', '700'],
});

export default async function RootLayout({
  children,
  params,
}: {
  children: React.ReactNode;
  params: Promise<{ locale: string }>;
}) {
  const { locale } = await params;
  const isRTL = locale === 'he';

  return (
    <html lang={locale} dir={isRTL ? 'rtl' : 'ltr'}>
      <body className={tajawal.className}>{children}</body>
    </html>
  );
}

next/font 会自行托管字体（不会请求外部 Google Fonts，也不会产生布局偏移）。

React 与 MUI：

import { createTheme, ThemeProvider } from '@mui/material/styles';
import { CacheProvider } from '@emotion/react';
import createCache from '@emotion/cache';
import rtlPlugin from 'stylis-plugin-rtl';
import { prefixer } from 'stylis';

const cacheRtl = createCache({
  key: 'muirtl',
  stylisPlugins: [prefixer, rtlPlugin],
});

const theme = createTheme({ direction: 'rtl' });

步骤 6：检查常见问题

1. 带有方向含义的图标（箭头、返回按钮）——应镜像
2. 进度条——应从右向左填充
3. 滑块／轮播组件——滑动方向应反转
4. 表单标签——应右对齐
5. 面包屑——分隔符方向应反转
6. 表格——检查表头和单元格的对齐方式
7. 图表——对于阿拉伯语读者，可能需要反转 x 轴

示例

示例 1：将 LTR 组件转换为 RTL

用户说：“让这个卡片组件支持阿拉伯语”

之前（仅支持 LTR）：

.card {
  margin-left: 16px;
  padding-right: 12px;
  text-align: left;
  border-left: 3px solid blue;
}

之后（兼容 RTL）：

.card {
  margin-inline-start: 16px;
  padding-inline-end: 12px;
  text-align: start;
  border-inline-start: 3px solid blue;
}

使用 Tailwind 时，将 ml-4 pr-3 text-left border-l-4 替换为 ms-4 pe-3 text-start border-s-4。

示例 2：双向文本问题

用户说：“数字在我的阿拉伯语文本中显示顺序颠倒”

<p>התקשרו אלינו: 050-321-4450</p>


<p>התקשרו אלינו: <span dir="ltr">050-321-4450</span></p>

若仅使用 CSS，可在包含内容的 span 上使用 unicode-bidi: isolate。

示例 3：Tailwind RTL 导航

用户说：“我的侧边栏在阿拉伯语界面中出现在错误的一侧”

<aside class="fixed left-0 w-64">...</aside>


<aside class="fixed start-0 w-64">...</aside>


<button class="rtl:rotate-180">
  <ArrowLeftIcon />
</button>

附带资源

参考资料

• references/css-logical-properties.md — 完整的 CSS 物理属性到逻辑属性映射表（margin、padding、border、定位、文本对齐、尺寸），以及无衬线、衬线和等宽字体的阿拉伯语字体栈建议。将任何 LTR 样式表转换为兼容 RTL 的逻辑属性，或选择阿拉伯语网页字体时，请查阅此资料。

易踩坑

• CSS 的 text-align: left 不适用于阿拉伯语。应使用 text-align: start，它会遵循文档方向。Agent 经常在 CSS 中硬编码 left 对齐。
• 在 RTL 模式下，margin-left 和 padding-right 不会翻转。应改用 CSS 逻辑属性：margin-inline-start 和 padding-inline-end。基于 LTR CSS 训练的 Agent 会生成物理属性。
• Flexbox 的 row 方向会在 RTL 中自动反转，但 row-reverse 也会反转，导致方向再次翻转回 LTR。Agent 可能会添加 row-reverse，以为这样能实现 RTL，但实际上它会在 RTL 上下文中创建 LTR 布局。
• 电话号码、信用卡号和代码片段即使位于 RTL 容器内，也必须保持 LTR。请将它们包裹在 <bdo dir="ltr"> 中，或在其所在元素上使用 direction: ltr。Agent 经常会让这些内容继承 RTL。

参考链接

来源	URL	检查内容
MDN CSS 逻辑属性	https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values	完整的属性列表、浏览器支持表
Tailwind CSS RTL 支持	https://tailwindcss.com/docs/hover-focus-and-other-states#rtl-support	rtl: / ltr: 变体语法
Tailwind 逻辑属性	https://tailwindcss.com/docs/margin#logical-properties	ms-*、me-*、ps-*、pe-* 工具类
Google Fonts 阿拉伯语字体	https://fonts.google.com/?subset=arabic	可用的阿拉伯语字体系列
W3C 国际化	https://www.w3.org/International/articles/inline-bidi-markup/	Unicode 双向文本算法、标记最佳实践

故障排查

错误："文本对齐看起来不对"

原因：使用了 text-align: left，而不是 text-align: start 解决方案：将 text-align 中所有的 left / right 替换为 start / end。

错误："布局没有镜像"

原因：使用了物理边距／内边距，而不是逻辑属性 解决方案：将所有 margin-left / margin-right 替换为 margin-inline-start / margin-inline-end。