Maestro 多语言测试完全指南：3 步搭好跨语言本地化验证流程-育师

Maestro 多语言测试完全指南：3 步搭好跨语言本地化验证流程

【免费下载链接】MaestroPainless E2E Automation for Mobile and Web项目地址: https://gitcode.com/GitHub_Trending/ma/Maestro

Maestro 是一款面向移动端的端到端自动化测试工具，支持 Android、iOS 与 Web 三端。本文聚焦一个被低估的场景：多语言测试。传统做法是每次手动改系统语言、逐页比对文案，而 Maestro 的--device-locale参数可以在启动模拟器时就切换设备语言，再用一份 YAML 流程自动断言翻译文案，把语言回归从小时级压到分钟级。

一、环境准备：装好工具并选对 locale 代码

1.1 环境检查与 CLI 安装

先确认本地 Java 版本，再安装 CLI：

java -version # 需要 17 或更高 curl -fsSL "https://get.maestro.mobile.dev" | bash

这两行分别验证 Java 环境是否满足要求，以及通过官方脚本安装 Maestro CLI。装好后可以用maestro --version快速确认。

1.2 理解 locale 代码格式：三端并不统一

这是最容易踩的坑。从源码 maestro-client locale 定义可以看到，三端的合法写法各不相同：

平台	代码格式	示例
Android	`语言_国家`（下划线）	`zh_CN`、`ja_JP`、`en_US`
iOS	下划线与连字符混排	`en_US`、`pt-BR`、`zh-HK`
Web	目前仅支持	`en_US`

写错的代价不是"静默失败"，而是直接抛LocaleValidationException并打印支持列表，属于快速失败，反而好排查。

二、跑通第一个多语言测试流程

2.1 启动指定语言的模拟器

maestro start-device --device-locale zh_CN

这条命令负责启动（或复用）模拟器，并在系统层面把语言切到简体中文。之后启动的应用读取到的就是中文系统环境。

2.2 一个最小可运行的断言流程

appId: com.example.shop --- - launchApp - assertVisible: "立即支付" # 验证中文翻译已生效 - tapOn: "购物车" - assertVisible: "共 2 件商品" - assertNotVisible: "Payment" # 反向断言：英文残留即漏翻

这段 YAML 做什么：启动应用后先确认关键按钮是中文，进入购物车页面核对文案，最后用assertNotVisible反向检查是否残留英文字符串——它比正向断言更能揪出"部分漏翻"的问题。

Maestro 多语言测试的运行环境示意：模拟器语言切换后，流程自动完成文案断言

三、用环境变量让一份 YAML 覆盖所有语言

3.1 断言文案参数化

把"每语言一个文件"改成"一个文件 + 环境变量"：

env: UI_LANG: zh --- - launchApp - assertVisible: "登录" - assertVisible: "注册" - tapOn: "登录" - assertVisible: "请输入手机号"

这个流程把要验证的文案直接写在断言里，配合env区分语言版本，同一份结构即可复制出中文、日文、德文等多份流程，避免为每种语言重复维护交互步骤。

3.2 地区格式验证：货币与日期

地区化不只是翻译，还包括格式。用正则断言做兜底最稳：

- launchApp - assertVisible: text: "\\d+\\.\\d{2}\\s*¥" # 价格必须带人民币符号 - assertVisible: text: "202[4-9]年\\d{1,2}月" # 中文日期格式

这两条正则断言分别检查"金额后带 ¥"与"中文年月格式"，即使具体数字变化，格式错了照样能被发现。

四、Android、iOS、Web 三端覆盖差异

4.1 各端 locale 支持一览

平台	支持范围	备注
Android	语言×国家组合动态校验	非法组合会被拒绝，错误信息附带全部合法代码
iOS	固定枚举，含连字符格式	如`zh-HK`、`pt-BR`，以 IosLocale.kt 中的枚举为准
Web	仅`en_US`	其余写法会在启动时报错

4.2 注意：应用内语言设置的优先级

Android 的"应用内语言"功能与 iOS 的语言/区域选择，都可能让 App 无视系统 locale。写多语言断言前，先确认被测应用的语言选择策略：若应用内默认值是英文，系统切到zh_CN后界面可能仍是英文。这类"测了但没生效"的情况，建议先在真机手动切一次系统语言确认行为，再固化进流程。

五、常见坑：现象、原因与验证办法

5.1 现象一：启动直接报 locale 错误

原因基本锁定为格式问题：给 iOS 传了zh_CN这类不在枚举里的写法，或给 Web 端传了en_US以外的值。验证办法是把报错信息里列出的合法代码与自己的写法逐字符比对（下划线/连字符、大小写）。

5.2 现象二：语言切换后界面没变

按顺序排查三处：一是应用内是否有语言设置覆盖了系统值；二是切换 locale 后是否需要重启应用（launchApp会冷启动，一般可覆盖）；三是模拟器本身是否被复用——start-device复用一个旧模拟器时，建议确认它确实是按新的 locale 启动的。

5.3 现象三：断言大面积失败但肉眼看着是对的

多半是文案含动态内容（数字、用户名）导致精确匹配失配。解决办法是把动态部分换成正则，只断言稳定的语言骨架，例如assertVisible: text: "共\\d+件商品"。

六、接入 CI：把多语言回归放进流水线

6.1 流水线脚本示例

# 循环覆盖目标语言，每个 locale 起一台模拟器独立执行 for LOCALE in zh_CN ja_JP de_DE; do maestro start-device --device-locale "$LOCALE" maestro test ./flows/i18n-check.yaml done

这段脚本让 CI 依次为每种语言拉起模拟器并跑同一份断言流程，任一语言失败即中断构建，实现"每次发布前全语言回归"。