小程序国际化适配Skill — 小程序国际化适配技能

微信小程序境外用户体验适配 技能

帮助开发者消除境外用户在使用小程序时的体验卡点，从账号体系、信息录入、UI 排版三个维度提供完整的适配方案。

工作流程 第一步：运行自动扫描（工具无关）

对用户的小程序项目运行扫描工具，获取问题清单和优先级排序。不要依赖特定 AI 工具的环境变量（如 CLAUDE_技能_DIR）。

# 方式 A（推荐，适用于大多数工具）：先进入技能目录再执行 cd <技能目录>/验证 npm 安装 node 扫描-project.js --project <小程序项目路径>

# 方式 B（已安装依赖时，可直接从技能根目录执行） node 验证/扫描-project.js --project <小程序项目路径>

扫描工具输出 验证/报告s/扫描-报告.md 和 验证/报告s/扫描-结果.json，包含：

P0 (必须修复): 翻译后确定溢出的文案 / 账号表单硬阻塞（如 +86 硬编码、11 位长度校验、姓名仅限中文） P1 (建议修复): 翻译后可能溢出的文案 / CSS 固定宽度容器缺少 overflow 保护

扫描覆盖 4 种目标语言的溢出预测: English(3.0x)、Spanish(3.5x)、French(3.5x)、German(4.0x)。

若运行时报错 Cannot find 模块 'fast-glob'，说明依赖未安装，请在 验证 目录重新执行 npm 安装 后再运行。

第二步：基于扫描结果定位并修复

按 P0 -> P1 优先级，结合下方三个维度的适配指引和代码示例给出修复方案。

第三步：执行进度追踪

在回复中维护以下清单：

适配进度

• [ ] 1. 确认业务类型和目标用户群
• [ ] 2. 完成账号体系适配（手机号国际化 + 邮箱通道）
• [ ] 3. 完成信息录入字段国际化（证件/姓名/地址）
• [ ] 4. 完成搜索触达优化（小程序名称/简介补充英文，MP 后台操作）
• [ ] 5. 完成差异化UI策略实施（语言路由 + 国际版界面）
• [ ] 6. 完成多语言排版优化
• [ ] 7. 完成端到端测试验证
• [ ] 8. 完成上线前自检

• 账号体系

境外用户最常见的阻塞: 手机号只支持 +86、校验硬编码 11 位、无邮箱备选通道。

适配项 说明 优先级 兼容国际区号 允许用户选择非 +86 区号 P0 兼容国际号码位数 放宽"手机号必须为11位"的校验限制 P0 邮箱验证入口 国际短信可能延迟/拦截，邮箱是关键降级通道 P0 国际短信通道 接入 Twilio 等支持全球发送的短信服务商 P0

两种手机号收集方式:

方式一（推荐）: 接入微信"手机号快速验证"组件，平台已支持国际手机号返回 方式二: 自行搭建国际区号选择器 + 验证码通道，需根据区号动态校验位数

完整代码示例见 reference.md 第 1 节。

• 信息录入

字段 原始限制 适配后 优先级 姓名字符集 仅汉字 汉字 + 英文 + 空格 + 连字符 + 撇号 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 节。

• 差异化 UI 与排版优化

3.1 语言路由分流

通过 wx.获取应用Base信息() 检测用户语言，对非中文用户隐藏营销弹窗、裂变分享、积分任务等国内特有功能，保留核心服务入口。

组件 国内版 国际版 营销弹窗 显示 隐藏 裂变分享入口 显示 隐藏 积分任务体系 显示 隐藏 核心服务入口 显示 显示 通用图标 按需 增加（减少对纯文本的依赖） 3.2 翻译后溢出预测

中文文案翻译后变长（如"提交" -> "Einreichen"），在固定宽度容器中溢出。扫描工具已内置此检测能力。

溢出风险扫描模式速查:

风险模式 识别方法 修复方向 固定宽度容器 + 无 overflow width: Nrpx 且无 overflow/text-overflow/word-break 改为 min-width + p添加ing 或加 text-overflow: ellipsis 固定高度单行文本 height 和 line-height 相同，无 overflow 改用 min-height 或加 overflow: hidden !导入ant 修饰的尺寸 width: Nrpx !导入ant 移除 !导入ant，改为弹性布局 纯中文假设的宽度 中文 N 字对应的固定宽度 改为 p添加ing + min-width 自适应 无 word-break 的全局样式 应用.wxss 缺少全局排版防护 全局添加 word-break: break-word

溢出风险判定:

比率（估算宽度 / 容器宽度） 风险等级 含义

1.0 HIGH 几乎确定溢出，必须修复

0.8 - 1.0 MEDIUM 有溢出风险，建议修复 < 0.8 LOW 溢出可能性小

完整代码示例见 reference.md 第 4 节。

• 优先级速查表

优先级 适配项 说明 P0 手机号兼容国际区号和位数 直接影响用户注册和使用 P0 邮箱验证入口 短信不可达时的关键降级通道 P0 证件类型扩展 + 姓名规则放宽 实名场景下的基本可用性 P1 小程序名称/简介补充英文 提升境外搜索触达率；MP 后台设置双语名称（如"故宫 Forbidden City"），project.config.json 的 projectname 和 应用.json 的 navigationBarTitleText 不应为默认值 P1 国际短信服务商接入 保障验证码送达 P2 多语言适配 平台翻译已可用（零成本）；自建 i18n 为可选增强方案，详见 reference.md 第 3 节 P2 差异化 UI（语言路由分流） 减少境外用户理解成本 安全提醒 手机号和邮箱等用户信息必须加密存储，不得明文记录在日志中 验证码需设置有效期（建议 5 分钟） 限制验证码发送频率，防止短信轰炸攻击 国际短信服务商 API 密钥不得出现在前端代码或公共仓库中 AI 输出模板

结论

[一句话说明当前适配状态/已定位的问题]

执行清单

• 已完成：

- [item]

• 待完成：

- [item]

风险与阻塞

• [风险或阻塞项]

下一步

• [最小可执行动作]
• [下一步验证动作]

问题反馈与交流通道 小程序境外开放交流专区: https://developers.weixin.qq.com/community/minihome/mixflow/3721056300659130376 小程序境外业务邮箱: miniprogram_global@tencent.com