mcpField
E
experience-lwc-rtl-validate

experience-lwc-rtl-validate

github.com/forcedotcom测试与质量1.1k2.3k 次安装1 天前更新
代码仓库

关于 experience-lwc-rtl-validate

用于审查 Lightning Web Component（LWC）从右向左（RTL）本地化合规性的技能，适合准备支持阿拉伯语、希伯来语等 RTL 语言的团队。它结合 CSS 扫描和代码检查生成问题报告，并可应用修复。

主要功能

  1. 01扫描 CSS 物理方向属性
  2. 02检查模板与脚本中的方向逻辑
  3. 03遵循 SLDS 的 RTL 约束
  4. 04生成带修复建议的审查报告
  5. 05复查修复并运行测试

适用场景

  1. 01发布 LWC 前检查 RTL 合规性
  2. 02排查 RTL 环境中的布局缺陷
  3. 03验证 CSS 重构后的 SLDS 用法

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/forcedotcom/sf-skills --skill experience-lwc-rtl-validate

安装后在 Claude Code 中输入/experience-lwc-rtl-validate确认已加载。

附带文件references/rtl-expert.mdscripts/scan-rtl-css.sh

详细介绍

审查 LWC RTL

对 Lightning Web Component 执行结构化的从右到左（RTL）国际化合规检查，生成问题报告和代码级修复建议，使组件符合 Salesforce RTL 指南。

适用场景

  • 用户要求对特定 LWC 进行“RTL review”“i18n check”“RTL compliance pass”或“RTL audit”。
  • 为在 RTL 区域设置中发布组件做准备（阿拉伯语、希伯来语、波斯语、乌尔都语）。
  • 调查 RTL 环境中报告的布局缺陷。
  • 在 CSS 重构后验证 SLDS 类的使用情况。

请勿将此技能用于：

  • 构建新组件（使用 experience-lwc-generate）。
  • 修改 SLDS 类本身（使用 design-systems-slds-apply 或 design-systems-slds2-migrate）。
  • 无障碍或安全审查——请使用相关工具单独执行这些检查。
  • 使用功能标志控制修复（修复完成后再添加功能标志控制）。

前提条件

  • 组件路径（modules/… 下的 LWC 包）。
  • 有权访问组件的 HTML 模板、JS/TS 和 CSS。

知识库

参考资料是唯一事实来源。请勿凭记忆总结——打开参考资料、应用其中的指南，并在报告中引用所用的具体章节。

工作流

第 1 步 — 确定审查范围

收集组件路径，并确定要审查的文件：.html、.js/.ts、.css，以及由目标组件调用且由同一团队负责的任何子组件。

记录现有的功能标志控制（例如 Aura.org.rtlPhase1FixEnabled）——需要修改代码的问题必须遵循这些控制。

第 2 步 — 阅读知识库

从头到尾阅读 RTL Expert，然后再进行判断。该资料列出了物理属性到逻辑属性的映射、双向文本处理模式，以及至关重要的、优先于通用 RTL 建议的 SLDS 约束。

第 3 步 — 检查 CSS

对包中的每个 .css 文件运行确定性扫描器。扫描器仅匹配 CSS 声明——不会匹配 HTML class="…" 属性中的 SLDS 类名（见第 5 步）。 必须单独扫描内联 style="…" 属性（可将其提取到临时文件中，或手动检查 HTML 并应用相同规则）。

"<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——请手动检查角落简写，并转换为逻辑角变体。

步骤 4 — HTML / JS 检查

检查模板和 JS，确认以下内容：

  • 图标翻转提示 — 仅标记使用普通 HTML <img> / 内联 SVG / 原始 Unicode / background-image CSS 且具有方向语义的图标。不要标记 LWC 模板中的 <lightning-icon>（包括 utility:chevronright、utility:chevronleft、utility:back、utility:forward 等方向性 utility 名称）；lightning-icon 通过 Lightning 图标服务渲染，该服务会在 RTL 语言环境中自动镜像方向性 utility 图标。请按处理 SLDS utility 类的方式处理它。
  • dir 属性的用法 — 确认其值来自语言环境，而不是硬编码。
  • 键盘方向键语义 — 对于方向性导航（标签栏、滑块、树形展开/折叠），Left/Right 方向键处理程序应在 RTL 中对调。
  • 方向性 Unicode 控制符 — 确保渲染用户生成的文本时，不会剥除 RLM/LRM 标记。
  • 带物理属性的内联 style="…" — 适用与步骤 3 相同的规则。
步骤 5 — SLDS 限制

SLDS 类处理是优先级最高的 RTL 规则。如果以下规则要求“不要标记”，该类就不得作为报告中的发现出现——无论是问题、修复建议还是重命名建议，都不可以。

  1. **带有 _left / _right 后缀的 SLDS utility 类支持 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 utility 类系列。保持原样。
  2. **SLDS 类不存在 _start / _end 变体。**绝不要将 slds-*_right 重命名为 slds-*_end，或将 slds-*_left 重命名为 slds-*_start。不存在这类名称；重命名会破坏样式表。如果你想通过添加 _start / _end 来“修复”某个 SLDS utility 类，立即停止——正确做法是保持该类不变（见规则 1）。
  3. **绝不要修改、重命名或移除任何 slds-* 类。**SLDS 提供了支持 RTL 的样式表；改动类会破坏约定。
  4. 如果自定义 CSS 重复了 SLDS 类已有的处理效果，正确的修复方式是移除，而不是转换。删除冗余的自定义规则；保留 SLDS 类不变。不要将被移除的属性转换为逻辑属性，也不要同时提出“移除 + 转换”两种方案；只有一种修复方式，就是删除。例如：.css 文件中有 float: right，模板中同时有 class="slds-button__icon_right"——删除整个 .custom-icon { float: right } 规则。不要“另外建议 float: inline-end”——这是错误的；SLDS 类已负责位置处理。
  5. 如果 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 类不属于发现项，不得出现在报告中。

步骤 6 — 生成报告

严格按照以下格式编写 <outputDir>/rtl-review.md（每个 ## 标题后空一行；每条摘要句都以句号结尾）：

## 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

## 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>.

从 scan-rtl-css.sh 的输出中填入 ## RTL 下的 CSS 发现项，并以相同格式附加步骤 4 中手动编写的 HTML/JS 发现项。若没有发现项，则在 ## RTL 下输出唯一条目 - No issues found.，并在 Summary 中报告 0 issues found; 0 fixed; 0 deferred.，同时提供一句概述和引用。

第 7 步 — 应用修复

对于每项已接受的问题：

  1. 编辑组件文件（CSS、HTML、JS/TS）以应用修复。
  2. 保留现有的正确行为和功能标志门控。如果已配置门控（例如，Aura.org.rtlPhase1FixEnabled），则保持原样。只有在调用方明确要求对新修复进行分阶段发布时，才为该修复添加功能标志门控；否则直接应用修复。
  3. 不要移除或重命名 SLDS 类。
  4. 不要悄悄删除旧代码——需要门控时，请保留原有路径。
第 8 步 — 验证
  • 对更新后的文件重新执行审查；每项已修复的问题都不应再出现。
  • 运行 Jest 测试和任何组件级 RTL 视觉测试。

交叉引用

  • 相关技能：
    • design-systems-slds-apply — 用于超出自定义 CSS 清理范围的 SLDS 类级更改。
    • design-systems-slds2-migrate — 当 RTL 清理发现需要先迁移到 SLDS2 的类时使用。
    • experience-lwc-generate — 当审查发现需要重新生成组件，而非打补丁时使用。
    • 无障碍（WCAG 2.2）和安全（LWS + Product Security）审查是独立流程——请使用相应工具执行，而非使用此技能。
    • 功能标志门控不在此技能的范围内；仅当调用方明确要求分阶段发布时，才单独应用（参见第 7 步）。

验证

  • 更新后的组件通过所有 RTL 规则（对包中的每个 CSS 文件重新运行 scripts/scan-rtl-css.sh——对于每项已完全应用的修复，该脚本都必须返回空结果）。
  • 未修改、重命名或移除任何 SLDS 类。
  • 每项问题均已修复，或附有说明原因的明确延期备注。
  • rtl-review.md 符合第 6 步定义的双章节结构（每个 ## 后有空行；摘要句以句号结尾）。

评论

支持 Markdown