Install
openclaw skills install miniprogram-foreign-user-adaptation小程序国际化适配Skill
微信小程序境外用户体验适配。当开发者需要适配境外用户账号登录、表单国际化、英文搜索触达、多语言服务、翻译后排版溢出检测时使用此 Skill。
微信小程序境外用户体验适配 Skill
帮助开发者消除境外用户在使用小程序时的体验卡点，从账号体系、信息录入、UI 排版三个维度提供完整的适配方案。
工作流程
第一步：运行自动扫描（工具无关）
对用户的小程序项目运行扫描工具，获取问题清单和优先级排序。不要依赖特定 AI 工具的环境变量（如 CLAUDE_SKILL_DIR）。
# 方式 A（推荐，适用于大多数工具）：先进入技能目录再执行
cd <技能目录>/validation
npm install
node scan-project.js --project <小程序项目路径>
# 方式 B（已安装依赖时，可直接从技能根目录执行）
node validation/scan-project.js --project <小程序项目路径>
扫描工具输出 validation/reports/scan-report.md 和 validation/reports/scan-result.json，包含：
- P0 (必须修复): 翻译后确定溢出的文案 / 账号表单硬阻塞（如 +86 硬编码、11 位长度校验、姓名仅限中文）
- P1 (建议修复): 翻译后可能溢出的文案 / CSS 固定宽度容器缺少 overflow 保护
扫描覆盖 4 种目标语言的溢出预测: English(3.0x)、Spanish(3.5x)、French(3.5x)、German(4.0x)。
若运行时报错 Cannot find module 'fast-glob'，说明依赖未安装，请在 validation 目录重新执行 npm install 后再运行。
第二步：基于扫描结果定位并修复
按 P0 -> P1 优先级，结合下方三个维度的适配指引和代码示例给出修复方案。
第三步：执行进度追踪
在回复中维护以下清单：
## 适配进度
- [ ] 1. 确认业务类型和目标用户群
- [ ] 2. 完成账号体系适配（手机号国际化 + 邮箱通道）
- [ ] 3. 完成信息录入字段国际化（证件/姓名/地址）
- [ ] 4. 完成搜索触达优化（小程序名称/简介补充英文，MP 后台操作）
- [ ] 5. 完成差异化UI策略实施（语言路由 + 国际版界面）
- [ ] 6. 完成多语言排版优化
- [ ] 7. 完成端到端测试验证
- [ ] 8. 完成上线前自检
1. 账号体系
境外用户最常见的阻塞: 手机号只支持 +86、校验硬编码 11 位、无邮箱备选通道。
| 适配项 | 说明 | 优先级 |
|---|---|---|
| 兼容国际区号 | 允许用户选择非 +86 区号 | P0 |
| 兼容国际号码位数 | 放宽"手机号必须为11位"的校验限制 | P0 |
| 邮箱验证入口 | 国际短信可能延迟/拦截，邮箱是关键降级通道 | P0 |
| 国际短信通道 | 接入 Twilio 等支持全球发送的短信服务商 | P0 |
两种手机号收集方式:
- 方式一（推荐）: 接入微信"手机号快速验证"组件，平台已支持国际手机号返回
- 方式二: 自行搭建国际区号选择器 + 验证码通道，需根据区号动态校验位数
完整代码示例见 reference.md 第 1 节。
2. 信息录入
| 字段 | 原始限制 | 适配后 | 优先级 |
|---|---|---|---|
| 姓名字符集 | 仅汉字 | 汉字 + 英文 + 空格 + 连字符 + 撇号 | P0 |
| 姓名长度 | 2-10 字符 | 1-50 字符 | P0 |
| 证件类型 | 仅身份证 | 身份证 + 护照 + 永居证 + 港澳台通行证 | P0 |
| 手机号位数 | 固定 11 位 | 按区号动态校验（8-15 位） | P0 |
| 手机号区号 | 仅 +86 | 支持国际区号选择 | P0 |
| 地址格式 | 省/市/区三级联动 | 增加自由文本输入选项 | P1 |
核心修改点: 证件类型需扩展护照等选项并用宽松正则校验；姓名正则从 [\u4e00-\u9fa5]{2,10} 放宽为 [\u4e00-\u9fa5A-Za-z\s\-'\.]{1,50}；地址增加境外用户自由文本输入。
完整代码示例见 reference.md 第 2 节。
3. 差异化 UI 与排版优化
3.1 语言路由分流
通过 wx.getAppBaseInfo() 检测用户语言，对非中文用户隐藏营销弹窗、裂变分享、积分任务等国内特有功能，保留核心服务入口。
| 组件 | 国内版 | 国际版 |
|---|---|---|
| 营销弹窗 | 显示 | 隐藏 |
| 裂变分享入口 | 显示 | 隐藏 |
| 积分任务体系 | 显示 | 隐藏 |
| 核心服务入口 | 显示 | 显示 |
| 通用图标 | 按需 | 增加（减少对纯文本的依赖） |
3.2 翻译后溢出预测
中文文案翻译后变长（如"提交" -> "Einreichen"），在固定宽度容器中溢出。扫描工具已内置此检测能力。
溢出风险扫描模式速查:
| 风险模式 | 识别方法 | 修复方向 |
|---|---|---|
| 固定宽度容器 + 无 overflow | width: Nrpx 且无 overflow/text-overflow/word-break | 改为 min-width + padding 或加 text-overflow: ellipsis |
| 固定高度单行文本 | height 和 line-height 相同，无 overflow | 改用 min-height 或加 overflow: hidden |
!important 修饰的尺寸 | width: Nrpx !important | 移除 !important，改为弹性布局 |
| 纯中文假设的宽度 | 中文 N 字对应的固定宽度 | 改为 padding + min-width 自适应 |
无 word-break 的全局样式 | app.wxss 缺少全局排版防护 | 全局添加 word-break: break-word |
溢出风险判定:
| 比率（估算宽度 / 容器宽度） | 风险等级 | 含义 |
|---|---|---|
| > 1.0 | HIGH | 几乎确定溢出，必须修复 |
| 0.8 - 1.0 | MEDIUM | 有溢出风险，建议修复 |
| < 0.8 | LOW | 溢出可能性小 |
完整代码示例见 reference.md 第 4 节。
4. 优先级速查表
| 优先级 | 适配项 | 说明 |
|---|---|---|
| P0 | 手机号兼容国际区号和位数 | 直接影响用户注册和使用 |
| P0 | 邮箱验证入口 | 短信不可达时的关键降级通道 |
| P0 | 证件类型扩展 + 姓名规则放宽 | 实名场景下的基本可用性 |
| P1 | 小程序名称/简介补充英文 | 提升境外搜索触达率；MP 后台设置双语名称（如"故宫 Forbidden City"），project.config.json 的 projectname 和 app.json 的 navigationBarTitleText 不应为默认值 |
| P1 | 国际短信服务商接入 | 保障验证码送达 |
| P2 | 多语言适配 | 平台翻译已可用（零成本）；自建 i18n 为可选增强方案，详见 reference.md 第 3 节 |
| P2 | 差异化 UI（语言路由分流） | 减少境外用户理解成本 |
安全提醒
- 手机号和邮箱等用户信息必须加密存储，不得明文记录在日志中
- 验证码需设置有效期（建议 5 分钟）
- 限制验证码发送频率，防止短信轰炸攻击
- 国际短信服务商 API 密钥不得出现在前端代码或公共仓库中
AI 输出模板
## 结论
[一句话说明当前适配状态/已定位的问题]
## 执行清单
- 已完成：
- [item]
- 待完成：
- [item]
## 风险与阻塞
- [风险或阻塞项]
## 下一步
1. [最小可执行动作]
2. [下一步验证动作]