experience-lwc-rtl-validate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Reviewing LWC RTL

LWC RTL审查

Run a structured right-to-left (RTL) internationalization compliance pass over a Lightning Web Component, producing a report of issues found and code-level fixes to bring the component into compliance with Salesforce RTL guidelines.

对Lightning Web Component进行结构化的从右到左（RTL）国际化合规性检查，生成问题报告及代码级修复方案，使组件符合Salesforce RTL规范。

When to Use

使用场景

The user asks for an "RTL review", "i18n check", "RTL compliance pass", or "RTL audit" on a specific LWC.
Preparing a component for release in RTL locales (Arabic, Hebrew, Farsi, Urdu).
Investigating layout defects reported in RTL environments.
Verifying SLDS class usage after a CSS refactor.

Do NOT use this skill for:

Building new components (use
```
experience-lwc-generate
```
).

Modifying SLDS classes themselves (use

design-systems-slds-apply

design-systems-slds2-migrate

Accessibility or security review — run those as separate passes with the relevant tooling.
Gating a fix behind a feature flag (apply feature-flag gating after fixes land).

用户要求对特定LWC进行“RTL审查”、“i18n检查”、“RTL合规性验证”或“RTL审计”。
为RTL语言环境（阿拉伯语、希伯来语、波斯语、乌尔都语）准备组件发布。
排查RTL环境中报告的布局缺陷。
CSS重构后验证SLDS类的使用情况。

请勿将此技能用于：

构建新组件（使用
```
experience-lwc-generate
```
）。

修改SLDS类本身（使用

design-systems-slds-apply

或

design-systems-slds2-migrate

）。

可访问性或安全审查——使用相关工具单独执行这些检查。
通过功能标志控制修复（修复完成后再应用功能标志控制）。

Prerequisites

前置条件

Component path (LWC bundle under
```
modules/…
```
).
Access to the component's HTML templates, JS/TS, and CSS.

组件路径（位于
```
modules/…
```
下的LWC包）。
可访问组件的HTML模板、JS/TS及CSS文件。

Knowledge Base

知识库

The reference is the source of truth. Do not summarize from memory — open the reference, apply the guidelines, and cite the specific section you used in the report.

RTL internationalization: RTL Expert

参考文档为权威依据。请勿凭记忆总结——打开参考文档，应用规范，并在报告中引用所使用的具体章节。

RTL国际化：RTL Expert

Workflow

工作流程

Step 1 — Scope the review

步骤1 — 确定审查范围

Collect the component path and identify the files to review:

.html

.js

.ts

.css

, and any child components owned by the same team that are invoked from the target.

Note any existing feature-flag gates (e.g.,

Aura.org.rtlPhase1FixEnabled

) — findings that require code changes must respect them.

收集组件路径，确定需要审查的文件：

.html

、

.js

.ts

、

.css

，以及目标组件调用的、同一团队维护的所有子组件。

记录任何已有的功能标志控制（如

Aura.org.rtlPhase1FixEnabled

）——需要修改代码的问题必须遵循这些控制规则。

Step 2 — Read the knowledge base

步骤2 — 阅读知识库

Read RTL Expert top-to-bottom before judging. It enumerates the physical-to-logical property mappings, bidirectional text handling patterns, and — critically — the SLDS constraints that override generic RTL advice.

在判断之前，完整阅读RTL Expert。该文档列举了物理属性到逻辑属性的映射、双向文本处理模式，以及至关重要的、覆盖通用RTL建议的SLDS约束。

Step 3 — CSS inspection

步骤3 — CSS检查

Run the deterministic scanner over every

.css

file in the bundle. The scanner matches CSS declarations only — never SLDS class names in HTML
class="…"
attributes (see Step 5). Inline

style="…"

attributes must be scanned separately (either by extracting them into a temp file or by inspecting the HTML by hand and applying the same rules).

bash

"<skill_dir>/scripts/scan-rtl-css.sh" <cssFile1> [<cssFile2> ...]

Each output line has the shape

<file>:<line>: <property>: <value> -> <logical-property>: <logical-value>

. The scanner tokenizes declarations (splits on

inside

{…}

) so minified multi-declaration lines produce one finding per physical declaration and selector names are never rewritten. Translate each line into a Step 6 bullet (

<file>:<line> — <pattern> → <logical property>

plus a one-sentence Fix). Empty output IS a valid result — record it as "No issues found." in the report.

Scanner-recognised patterns (kept in sync with the script's regex — do not add rules here without also updating

scan-rtl-css.sh

left

right

→

inset-inline-start

inset-inline-end

margin-left

margin-right

→

margin-inline-start

margin-inline-end

padding-left

padding-right

→

padding-inline-start

padding-inline-end

text-align: left

right

→

text-align: start

end

border-left-*

border-right-*

→

border-inline-start-*

border-inline-end-*

float: left

float: right

→

float: inline-start

float: inline-end

(or remove and use flex/grid)

```
transform: translateX(...)
```
— flagged; sign-flip or use a logical alternative

border-radius

with explicit corners is not scanned automatically — inspect corner shorthand by hand and translate to the logical corner variants.

对包中的每个

.css

文件运行确定性扫描器。**扫描器仅匹配CSS声明——绝不匹配HTML

class="…"

属性中的SLDS类名（见步骤5）。**内联

style="…"

属性必须单独扫描（要么提取到临时文件，要么手动检查HTML并应用相同规则）。

bash

"<skill_dir>/scripts/scan-rtl-css.sh" <cssFile1> [<cssFile2> ...]

每条输出行的格式为

<file>:<line>: <property>: <value> -> <logical-property>: <logical-value>

。扫描器会将声明分词（在

{…}

内按

拆分），因此压缩后的多声明行每个物理声明都会生成一个问题，且选择器名称不会被重写。将每行内容转换为步骤6中的项目符号（

<file>:<line> — <pattern> → <logical property>

加上一句话的修复说明）。空输出是有效结果——在报告中记录为“未发现问题。”。

扫描器识别的模式（与脚本的正则表达式保持同步——若在此处添加规则，必须同时更新

scan-rtl-css.sh

）：

left

right

→

inset-inline-start

inset-inline-end

margin-left

margin-right

→

margin-inline-start

margin-inline-end

padding-left

padding-right

→

padding-inline-start

padding-inline-end

text-align: left

right

→

text-align: start

end

border-left-*

border-right-*

→

border-inline-start-*

border-inline-end-*

float: left

float: right

→

float: inline-start

float: inline-end

（或移除并使用flex/grid）

```
transform: translateX(...)
```
— 标记为问题；需反转符号或使用逻辑替代方案

带明确角的

border-radius

不会被自动扫描——手动检查角简写并转换为逻辑角变体。

Step 4 — HTML / JS inspection

步骤4 — HTML / JS检查

Walk templates and JS for:

Icon flipping hints — flag only icons with directional semantics that appear in plain HTML
<img>
/ inline SVG / raw Unicode / background-image CSS. Do NOT flag
<lightning-icon>
in LWC templates (including directional utility names like
```
utility:chevronright
```
,
```
utility:chevronleft
```
,
```
utility:back
```
,
```
utility:forward
```
);
```
lightning-icon
```
renders through the Lightning icon service, which mirrors directional utility icons automatically in RTL locales. Treat it the same way you treat SLDS utility classes.
```
dir
```
attribute usage — confirm it's sourced from locale, not hardcoded.
Keyboard arrow-key semantics — Left/Right arrow handlers should swap in RTL where navigation is directional (tab bars, sliders, tree expand/collapse).
Directional Unicode controls — ensure user-generated text is not stripped of RLM/LRM markers when rendered.
Inline
```
style="…"
```
with physical properties — same rules as Step 3.

检查模板和JS中的以下内容：

图标翻转提示——仅标记具有方向语义且出现在纯HTML
<img>
/ 内联SVG / 原始Unicode / background-image CSS中的图标。请勿标记LWC模板中的
<lightning-icon>
（包括方向型工具类名称如
```
utility:chevronright
```
、
```
utility:chevronleft
```
、
```
utility:back
```
、
```
utility:forward
```
）；
```
lightning-icon
```
通过Lightning图标服务渲染，会在RTL语言环境中自动镜像方向型工具图标。处理方式与SLDS工具类相同。
```
dir
```
属性的使用——确认其来源于语言环境，而非硬编码。
键盘箭头键语义——在RTL环境中，当导航具有方向性时（标签栏、滑块、树形展开/折叠），左右箭头处理程序应互换。
方向型Unicode控制——确保用户生成的文本在渲染时不会被剥离RLM/LRM标记。
包含物理属性的内联
```
style="…"
```
——遵循步骤3的相同规则。

Step 5 — SLDS constraints

步骤5 — SLDS约束

SLDS class handling is the highest-priority RTL rule. When a rule below says "do NOT flag", that class must not appear as a finding in the report — not as an issue, not as a "fix", not as a rename suggestion.

SLDS utility classes with
_left
/
_right
suffixes are RTL-aware and MUST NOT be flagged. They already mirror automatically in RTL under the hood — this includes
```
slds-text-align_right
```
,
```
slds-text-align_left
```
,
```
slds-m-left_*
```
,
```
slds-m-right_*
```
,
```
slds-p-left_*
```
,
```
slds-p-right_*
```
,
```
slds-float_left
```
,
```
slds-float_right
```
,
```
slds-border_left
```
,
```
slds-border_right
```
, and the rest of the
```
_left
```
/
```
_right
```
utility family. Leave them exactly as written.
_start
/
_end
variants of SLDS classes DO NOT EXIST. Never rename
```
slds-*_right
```
→
```
slds-*_end
```
or
```
slds-*_left
```
→
```
slds-*_start
```
. There is no such class; the rename would break the stylesheet. If you are tempted to "fix" an SLDS utility class by adding
```
_start
```
/
```
_end
```
, STOP — the correct action is to leave the class alone (see rule 1).
Never modify, rename, or remove any
slds-*
class. SLDS ships RTL-aware stylesheets; altering classes breaks the contract.
If custom CSS duplicates what an SLDS class already handles, the fix is removal — not conversion. Delete the redundant custom rule; leave the SLDS class alone. Do NOT convert the removed property to its logical equivalent, and do NOT offer removal + conversion as two alternatives; there is one fix, and it is deletion. Example:
```
float: right
```
in a
```
.css
```
file next to
```
class="slds-button__icon_right"
```
in the template — delete the entire
```
.custom-icon { float: right }
```
rule. Do not "also suggest
```
float: inline-end
```
" — that would be wrong; the SLDS class already handles placement.
If an SLDS class has an RTL gap, add complementary custom CSS rather than altering the SLDS class.

Concrete negative example — a template with

<span class="slds-text-align_right slds-m-right_small">…</span>

alongside a custom

padding-left: 4px

in the component's CSS: the ONLY finding is the CSS

padding-left

(Step 3). The two

slds-*_right

classes are not findings and must not appear in the report.

SLDS类处理是优先级最高的RTL规则。当以下规则说明“请勿标记”时，该类不得作为问题出现在报告中——既不能作为问题，也不能作为“修复”或重命名建议。

**带有
```
_left
```
/
```
_right
```
后缀的SLDS工具类支持RTL，且不得被标记。**它们在底层已实现RTL自动镜像——包括
```
slds-text-align_right
```
、
```
slds-text-align_left
```
、
```
slds-m-left_*
```
、
```
slds-m-right_*
```
、
```
slds-p-left_*
```
、
```
slds-p-right_*
```
、
```
slds-float_left
```
、
```
slds-float_right
```
、
```
slds-border_left
```
、
```
slds-border_right
```
以及所有其他
```
_left
```
/
```
_right
```
工具类家族。保持原样即可。
**SLDS类的
```
_start
```
/
```
_end
```
变体不存在。**切勿将
```
slds-*_right
```
重命名为
```
slds-*_end
```
，或将
```
slds-*_left
```
重命名为
```
slds-*_start
```
。不存在此类重命名后的类，重命名会破坏样式表。如果您想要通过添加
```
_start
```
/
```
_end
```
来“修复”SLDS工具类，请停止——正确的做法是保持该类不变（见规则1）。
**切勿修改、重命名或删除任何
```
slds-*
```
类。**SLDS提供支持RTL的样式表；修改类会破坏约定。
如果自定义CSS重复了SLDS类已实现的效果，修复方式是移除——而非转换。删除冗余的自定义规则；保持SLDS类不变。请勿将移除的属性转换为其逻辑等价形式，也不要提供移除+转换两种备选方案；只有一种修复方式，即删除。示例：
```
.css
```
文件中的
```
float: right
```
与模板中的
```
class="slds-button__icon_right"
```
并存——删除整个
```
.custom-icon { float: right }
```
规则。不要“同时建议使用
```
float: inline-end
```
”——这是错误的；SLDS类已处理了位置布局。
如果SLDS类存在RTL缺陷，添加补充性自定义CSS，而非修改SLDS类。

具体反例——模板中有

<span class="slds-text-align_right slds-m-right_small">…</span>

，同时组件CSS中有自定义的

padding-left: 4px

：唯一的问题是CSS中的

padding-left

（步骤3）。两个

slds-*_right

类不是问题，不得出现在报告中。

Step 6 — Produce the report

步骤6 — 生成报告

Write

<outputDir>/rtl-review.md

in this exact shape (blank line after each

##

heading; every summary sentence ends with a period):

markdown

undefined

按照以下精确格式在

<outputDir>/rtl-review.md

中编写报告（每个

##

标题后留空行；每个总结句以句号结尾）：

markdown

undefined

RTL

<file>:<line> — <physical pattern> → <logical property / SLDS class> Fix: <one-sentence explanation>; applied: yes/no
<file>:<line> — <physical pattern> → <logical property / SLDS class> Fix: <one-sentence explanation>; applied: yes/no

<file>:<line> — <physical pattern> → <logical property / SLDS class> Fix: <one-sentence explanation>; applied: yes/no
<file>:<line> — <physical pattern> → <logical property / SLDS class> Fix: <one-sentence explanation>; applied: yes/no

Summary

<n> issues found; <m> fixed; <k> deferred (with reason).
<one-sentence overview of what was found and why the remaining items are correct or deferred>.
Cite: RTL Expert — <section title>.


Populate the `## RTL` bullets from the `scan-rtl-css.sh` output for CSS findings, and append hand-authored bullets in the same shape for the Step 4 HTML/JS findings. When there are no findings, emit the single bullet `- No issues found.` under `## RTL` and a `Summary` that reports `0 issues found; 0 fixed; 0 deferred.` plus a one-sentence overview and citation.

<n> issues found; <m> fixed; <k> deferred (with reason).
<one-sentence overview of what was found and why the remaining items are correct or deferred>.
Cite: RTL Expert — <section title>.


CSS问题从`scan-rtl-css.sh`输出中提取填充到`## RTL`项目符号中，并以相同格式添加步骤4中HTML/JS问题的手动编写项目符号。当没有问题时，在`## RTL`下添加单个项目符号`- No issues found.`，并在`Summary`中报告`0 issues found; 0 fixed; 0 deferred.`，加上一句话概述和引用。

Step 7 — Apply fixes

步骤7 — 应用修复

For each accepted finding:

Edit the component files (CSS, HTML, JS/TS) to apply the fix.
Preserve existing correct behavior and existing feature-flag gates. If a gate is already configured (e.g.,
```
Aura.org.rtlPhase1FixEnabled
```
), leave it untouched. Only when the caller has explicitly required a phased rollout for a new fix, wrap that fix behind a feature flag; otherwise apply the fix directly.
Do NOT remove or rename SLDS classes.
Do NOT silently delete old code — preserve the original path where a gate is required.

对于每个已确认的问题：

编辑组件文件（CSS、HTML、JS/TS）以应用修复。
保留现有正确行为和已有的功能标志控制。如果已配置控制（如
```
Aura.org.rtlPhase1FixEnabled
```
），保持其不变。只有当调用者明确要求分阶段推出新修复时，才将该修复包装在功能标志后；否则直接应用修复。
请勿移除或重命名SLDS类。
请勿静默删除旧代码——当需要控制时保留原始路径。

Step 8 — Verify

步骤8 — 验证

Re-run the review against the updated files; every fixed finding must no longer appear.
Run Jest tests and any component-level RTL visual tests.

针对更新后的文件重新运行审查；每个已修复的问题必须不再出现。
运行Jest测试及任何组件级RTL可视化测试。

Cross-References

交叉引用

Related skills:
- ```
design-systems-slds-apply
```
  — for SLDS class-level changes beyond custom CSS cleanup.
- ```
design-systems-slds2-migrate
```
  — when RTL cleanup surfaces classes that need SLDS2 migration first.
- ```
experience-lwc-generate
```
  — when the review surfaces a need to regenerate the component rather than patch it.
- Accessibility (WCAG 2.2) and security (LWS + Product Security) reviews are separate passes — run them with the appropriate tooling for each, not this skill.
- Feature-flag gating is out of scope for this skill; apply it separately only when the caller has explicitly required a phased rollout (see Step 7).

相关技能：
- ```
design-systems-slds-apply
```
  — 用于自定义CSS清理之外的SLDS类级更改。
- ```
design-systems-slds2-migrate
```
  — 当RTL清理发现需要先迁移到SLDS2的类时使用。
- ```
experience-lwc-generate
```
  — 当审查发现需要重新生成组件而非打补丁时使用。
- 可访问性（WCAG 2.2）和安全（LWS + Product Security）审查是单独的检查流程——使用各自对应的工具执行，而非此技能。
- 功能标志控制不在此技能范围内；仅当调用者明确要求分阶段推出时才单独应用（见步骤7）。

Verification

验证标准

All RTL rules are green on the updated component (re-run
```
scripts/scan-rtl-css.sh
```
against every CSS file in the bundle — it must return empty for every fully-applied finding).
No SLDS class was modified, renamed, or removed.
Every finding has either been applied or has an explicit deferred note with a reason.
The
```
rtl-review.md
```
matches the two-section shape defined in Step 6 (blank line after each
```
##
```
; period-terminated summary sentences).

更新后的组件所有RTL规则均通过（对包中的每个CSS文件重新运行
```
scripts/scan-rtl-css.sh
```
——对于所有已完全应用的修复，扫描器必须返回空结果）。
未修改、重命名或删除任何SLDS类。
每个问题要么已应用修复，要么有明确的延迟说明及原因。
```
rtl-review.md
```
符合步骤6定义的两部分格式（每个
```
##
```
后留空行；总结句以句号结尾）。