Flutter .arb国际化文件中description字段作用及编写规范咨询

该字段内容是否会被VoiceOver读出？ #

• 不会。
• 这个字段从设计之初就不是给无障碍功能用的，它仅作为翻译人员的参考上下文存在，Flutter的l10n代码生成工具不会把这部分内容打包进最终运行的App里，既不会出现在渲染的界面上，也不会进入无障碍语义树，不管是iOS的VoiceOver还是安卓的TalkBack，都完全读取不到这部分内容。你可以直接编译项目查看生成的本地化代码，找不到任何description字段的相关运行时逻辑。

编写description字段的正确思路 #

这个字段的唯一服务对象是负责翻译文本的人员，核心作用是消除翻译歧义，所有内容都要围绕「让没接触过你App的翻译人员准确理解这个字符串的使用场景」来写，不需要包含给运行时、给终端用户看的内容。

必须包含的信息 #

• 字符串所在的页面/功能模块：比如是启动落地页、游戏关卡页、设置页还是错误弹窗
• 字符串对应的控件类型：是可点击按钮的文案、输入框占位提示、空状态说明、弹窗标题还是短时弹出的Toast提示
• 字符串对应的功能指代：比如同样是"Play"，是指启动游戏还是播放视频，同样是"Delete"是删除本地缓存还是注销账号，这类容易产生歧义的指向必须说清楚

不需要写的信息 #

• 精确的屏幕位置：比如"屏幕左上角距离边距16dp的按钮"这类UI布局细节完全没必要，翻译不需要知道控件的具体坐标
• 开发相关的技术细节：比如对应的Widget类名、路由路径、变量名这类和翻译无关的内容不需要写

你参考的I/O Pinball项目里的description写法就是很标准的范例："Text displayed on the landing page play button"，明确说了所在页面是落地页、控件是按钮、功能是启动游戏，翻译拿到就能准确翻译，不会出现歧义。

补充：如果你需要给VoiceOver等无障碍功能添加额外的提示文本，不要写在这个description字段里，应该通过Semantics组件配置对应的语义label、hint属性，这部分内容才会被系统无障碍服务读取。

内容的提问来源于stack exchange，提问作者Sunshine