# 国际化友好适配指南 随着外国用户来华数量日益增长，部分小程序存在手机号、证件、语言等限制，导致外国人用不了或用不好小程序。为改善外国用户体验，请开发者完成小程序国际化友好适配。 **【优化项】** 1. **账号体系适配（必需）**：登录、购票链路兼容非 + 86 国际手机号，放开国内 11 位手机号格式校验，或新增邮箱登录通道。 2. **信息录入适配（必需）**：实名、购票信息录入支持护照等境外身份证件，放宽姓名字符输入校验限制。 3. **多语言适配（重点）**：小程序已支持 **26** 种语言翻译，请关注翻译后页面及文本是否适配；为确保开发者小程序中的专有名词（如品牌名、产品词）翻译准确，请在小程序后台维护翻译词库。 4. **双语物料**：参照[平台中英双语物料规范](/miniprogram/design/MaterialDesign.md#%E4%B8%89%E3%80%81%E5%8F%8C%E8%AF%AD%E7%89%A9%E6%96%99)更新线下物料，优化外国用户扫码使用体验。 > **推荐使用国际化适配 Skill 快速定位代码优化项** > > - 使用指引：[小程序国际化适配 Skill](https://developers.weixin.qq.com/community/develop/article/doc/000806193d02d83050255826d6b413) > - SkillHub：[小程序国际化适配Skill — SkillHub](https://skillhub.cn/skills/miniprogram-foreign-user-adaptation) > - ClawHub：[小程序国际化适配Skill — ClawHub](https://clawhub.ai/tencent-adm/miniprogram-foreign-user-adaptation) > > 如有额外产品优化诉求或其他需求/反馈、技术问题可随时联系邮箱 miniprogram_global@tencent.com。 ## 一、账号体系适配（必需） > 注册登录和购票页面兼容非 +86 国际手机号和放宽 11 位手机号校验规则、或支持邮箱登录、或接入小程序手机号快速验证组件； ### 1.1. 兼容非 +86 国际手机号 手机号是来华旅游场景下（如景区门票预订、餐厅点餐、酒店入住等）关键的履约信息。 建议开发者通过平台手机号快速验证组件或自行搭建手机号验证码通道形式收集用户手机号，以适配入境用户的使用习惯。 #### 1.1.1. 国际手机号授权的接入方案 | 接入方式 | 接入方式说明 | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **接入“手机号快速验证”组件（推荐）** | 微信平台已对非个人主体且完成认证的小程序开放手机号快速验证组件服务，旨在帮助开发者向用户发起手机号申请。 具体内容参照指引：[手机号快速验证组件 \| 微信开放文档](open-ability/getPhoneNumber) | | **开发者自行搭建手机号验证码通道** | 开发者也可在小程序前端自行开发手机号填写及验证码发送的流程，以完成信息收集。 若涉及国际手机号的短信验证码下发，建议重点关注跨国发送的到达率。 - 建议接入支持全球发送的国际短信服务商：保障验证码能穿透境外运营商网络。 - 建议提供备选验证方案，例如：上行短信验证：允许用户主动发送特定代码到指定号码来完成验证。 - 语音验证：通过电话语音播报的方式告知用户验证码。 | _无论是直接获取微信绑定的手机号还是用户手动填写，底层系统均需支持国际号码格式。_ #### 1.1.2. 国际手机号的兼容逻辑 | 兼容方式 | 说明 | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | **兼容国际区号** | 放宽对于手机号国际区号的限制，允许用户在前端选择非 +86 开头的手机号进行填写。 ![](https://res8.wxqcloud.qq.com.cn/wxdoc/95b2c3ec-b10b-4fed-8819-1db4a712a920.png)| | **兼容国际号码位数** | 放宽对于“手机号必须为11位”的校验逻辑，避免境外手机号因长度问题被判定为错误手机号。 ![](https://res8.wxqcloud.qq.com.cn/wxdoc/f8c9a325-d9df-4c56-bcf2-60078b1a1416.png)| ### 1.2. 兼容邮箱登录验证 鉴于国际短信在跨国漫游场景下可能存在拦截或延迟，且海外用户具有高频使用电子邮箱的习惯，建议在手机号登录之外，增设“**邮箱+验证码**”或“**邮箱+密码**”的辅助验证/信息收集选项，确保在短信无法送达时，用户仍可通过邮箱完成身份验证并使用服务。 ![](https://res8.wxqcloud.qq.com.cn/wxdoc/87dde4a4-b67c-4c64-b364-3d1cce60abb2.png) ## 二、信息录入适配（必需） > 实名认证和购票信息支持护照等境外证件、放宽姓名输入校验规则； 在实名认证、物流填写、票务预订等场景中，若表单字段限制过严（例如：仅限汉字、仅支持身份证等），将导致境外用户无法录入有效信息。开发者可从以下方向开展适配优化。 | 优化方向 | 说明 | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **证件类型适配** | 在涉及实名制的业务场景中，在“居民身份证”之外，增设“护照”、“外国人永久居留身份证”等选项，并适配相应的证件号码校验规则。 ![](https://res8.wxqcloud.qq.com.cn/wxdoc/37ee0d0b-efa5-4926-83b1-c9e2c14d63fe.png)| | **姓名输入规则放宽** | - 取消“仅限汉字”的输入限制，允许输入英文字母及空格。 - 增加字符长度上限：考虑到外籍人士姓名音译或原名较长，建议姓名字段长度限制放宽至50个字符以上，避免截断。 ![](https://res8.wxqcloud.qq.com.cn/wxdoc/c4deed88-c407-470c-9d28-a13e89ae3e47.png) | ## 三、多语言适配（重点） > 小程序已支持 26 种语言翻译，请关注翻译的页面及文本适配，避免译文溢出或显示不全；为确保开发者小程序中专有名词（如品牌名、产品词）翻译准确，请在小程序后台维护翻译词库；开发者也可自行适配多语言界面； ### 3.1. 平台翻译能力适配 平台已为用户提供小程序翻译功能，支持 26 种语言。开发者可通过以下方式优化用户翻译功能在小程序的使用体验： | 多语言适配方式 | 适配方式说明 | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **页面适配（高优）** | 考虑多语言的文本长度、词汇分界等差异，开发者在小程序页面设计上，需要关注并适配翻译后文本内容过长而“溢出”的异常情况。 | | **文本规范（高优）** | 小程序翻译功能仅适用于文本翻译，无法识别图片中的文字。开发者在小程序页面设计上，避免使用图片代替文字，尽可能确保文本表达清晰、直观。 | | **词库维护** | 为确保开发者小程序中专有名词（如品牌名、产品词）翻译准确，平台支持开发者在[微信公众平台](https://mp.weixin.qq.com)维护自身小程序的翻译词库（小程序名称、品牌词、产品词、专业词汇等） 1. 登录[微信公众平台](https://mp.weixin.qq.com)前往「基础功能-翻译」下载翻译词库文件模版，填写词库文件上传 ![](https://res8.wxqcloud.qq.com.cn/wxdoc/862041e3-5a79-4ac7-8ca2-a9752ed4c1ef.png) 2. 确认翻译词库内容无误后，点击【确认生效】，当前平台审核版本的词库将正式生效 ![](https://res8.wxqcloud.qq.com.cn/wxdoc/899fe2a6-0443-40d5-9b11-d126ab93a8c2.png) **请注意：** • 翻译词库文件模版如下 ![](https://res8.wxqcloud.qq.com.cn/wxdoc/35c7ecfb-181c-4b8c-92d9-1b7b26d3368c.png) • 翻译词库Excel文件首列为小程序主语言，若小程序主语言为中文，则将中文放在A列；若小程序主语言为英文，则将英文放在A列，以此类推； • 若商户仅维护部分语言版本，在其余语言版本的翻译内容为空即可； | | **翻译动态适配** | 开发者可通过[wx.onUserTriggerTranslation](/miniprogram/dev/api/ui/menu/wx.onUserTriggerTranslation.md)监听用户触发小程序的翻译功能事件，并动态将页面核心内容（品牌词、产品词等）调整为目标翻译语言，平台识别到该内容已经为目标翻译语言后，将不会二次翻译。 示例： 1. 监听到用户开启翻译功能，目标语言为阿拉伯语 2. 开发者将页面内商品名称修改成阿拉伯语的专有词汇，其他内容不做翻译 3. 平台识别到商品名称已经是阿拉伯语，不做二次翻译，只翻译其他内容 | #### 小程序翻译功能说明 - **设置翻译语言**：目标翻译语言默认为微信客户端使用的语言。若需要调整翻译语言，用户可进入“我” - “设置” - “通用” - “翻译”从语言列表中选择翻译语言。 - **打开小程序翻译**：可使用两种方式（1）进入小程序，若右上角显示“翻译”气泡，点击“翻译”按钮；（2）点击小程序右上角的 “…” 按钮，在弹窗点击“翻译”按钮； - **小程序翻译支持 26 种语言**：简体中文、繁体中文（台湾）、繁体中文（香港）、英语、印度尼西亚语、马来语、西班牙语、韩语、意大利语、日语、葡萄牙语、俄语、泰语、越南语、阿拉伯语、土耳其语、德语、法语 ![](https://res8.wxqcloud.qq.com.cn/wxdoc/860e418d-6e3e-4b2c-9ece-5312dcf0ccf6.png) ### 3.2. 开发者自行适配多语言界面 开发者可通过以下两种接口感知用户客户端语言/目标翻译语言，并自行适配多语言： - 开发者可通过[wx.getAppBaseInfo](/miniprogram/dev/api/base/system/wx.getAppBaseInfo.md)接口，根据返回的language字段，获取用户客户端语言版本，在小程序内适配用户语言，并内置多语言切换功能。 - 开发者可通过[wx.onUserTriggerTranslation](/miniprogram/dev/api/ui/menu/wx.onUserTriggerTranslation.md)监听用户触发小程序的翻译功能事件，动态将页面的核心内容进行多语言适配。 - 若小程序的界面营销玩法较为复杂（如弹窗广告、裂变分享、积分任务）对于外国游客来说，理解成本极高且容易被视为干扰信息，同时可能造成页面自动翻译后的排版混乱。**开发者可考虑通过识别系统语言实施差异化的小程序界面**。 | 建议 | 说明 | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **智能路由分流（核心逻辑）** | • 开发者可通过 [wx.getAppBaseInfo](/miniprogram/dev/api/base/system/wx.getAppBaseInfo.md) 接口获取用户客户端语言版本（language 字段） • 当检测到非中文语言环境时，小程序自动加载国际化界面 | | **UI设计做减法** | • 聚焦核心功能：针对国际版界面，可移除复杂的营销弹窗、会员任务体系及非必要的社交裂变入口，只保留点餐、购票、支付、客服、地图等小程序自身核心服务路径。 • 视觉通用化：增加通用图标与示意图的使用比例，减少对纯文本说明的依赖，降低跨文化理解门槛。| ### 3.3. 自定义组件自行处理翻译（`wx://translate`） 若自定义组件使用服务端文案、第三方翻译服务或业务词库，或需要根据不同语言提供不同样式布局，可通过继承 `wx://translate` Behavior（基础库 **3.17.3** 起支持），由组件自行处理自身内容的翻译，同时让基础库继续自动翻译其内部的后代自定义组件。 ```js // 低版本声明 wx://translate 会因 Behavior 不存在而报错，需先判断基础库版本 const supportTranslateBehavior = compareVersion(wx.getAppBaseInfo().SDKVersion, '3.17.3') >= 0 Component({ // 低版本不声明该 Behavior，组件继续遵循原有自动翻译规则 behaviors: supportTranslateBehavior ? ['wx://translate'] : [], methods: { translateStatusChanged(context) { if (context.status === 'request') { // 当前会话的目标语言，例如 "en" 或 "zh_CN" this.loadTranslatedContent(context.targetLanguage) return } // 当前翻译会话已经失效 this.cancelTranslatedContent() }, }, }) ``` translateStatusChanged 类型定义： ```ts type SupportedLanguage = 'zh_CN' | 'en' | 'ar' | 'de' | 'es' | 'fr' | 'id' | 'it' | 'ja' | 'ko' | 'ms' | 'pt' | 'ru' | 'th' | 'vi' | 'tr' const translateStatusChanged = (ctx: Readonly<{ status: 'request' targetLanguage: SupportedLanguage } | { status: 'cancel' }>) => {} ``` | 关注点 | 说明 | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **生命周期** | `translateStatusChanged` 以组件实例作为 `this` 调用，并接收只读上下文。当前翻译会话首次遇到该组件时，组件至多收到一次 `request`（`targetLanguage` 为非空字符串）；用户关闭或回退翻译、翻译失败或被中断、页面销毁、目标语言切换时，已收到 `request` 的存活组件会收到一次 `cancel`。切换语言时，基础库保证先派发旧会话的 `cancel`，再派发新语言的 `request`。 | | **静态翻译边界** | 继承该 Behavior 后，基础库不会自动翻译组件自身的模板文本、可翻译属性、模板内内置组件的文本和属性，但仍会继续发现并处理后代自定义组件（含已投影到 slot 的后代组件）；嵌套的 `wx://translate` 组件各自形成独立边界。 | | **动态更新与异步任务** | 在 `request` 回调中调用 `setData` 时，组件自身新增的文本仍属于边界，基础库不会自动翻译；新增的后代普通自定义组件可在后续观察批次中进入自动翻译。基础库不会等待、取消、串行化或校验组件异步任务返回的 Promise，建议通过会话令牌等机制丢弃过期结果。 | | **`` 场景** | 嵌入 `` 的 HTML 内容由浏览器翻译路径单独处理，不会触发 `translateStatusChanged`；如需控制 HTML 内容，请在对应网页中实现自己的翻译策略。 | > 不要只声明同名方法而省略 `behaviors: ['wx://translate']`。未继承该 Behavior 的组件不会收到生命周期通知，也会继续遵循原有自动翻译规则。该 Behavior 自基础库 3.17.3 起支持，低版本须按上述方式降级为不声明，否则会因 Behavior 不存在而报错。 ## 四、双语物料 平台提供[中英双语小程序物料设计指](/miniprogram/design/MaterialDesign.md#%E4%B8%89%E3%80%81%E5%8F%8C%E8%AF%AD%E7%89%A9%E6%96%99)引供商户更新线下物料，外国人线下扫码体验更友好； ![](https://res8.wxqcloud.qq.com.cn/wxdoc/7558d7e2-fd54-4d8e-bdce-2c75f73d40ff.png)