SuperAPI AI 工具集

vgv-internationalization

前端与建站

查看项目

更新于 10-16 04:17

技能介绍

用途

该技能面向 Flutter 应用的国际化(i18n)与本地化(l10n)工作,提供一套最佳实践,帮助开发者使用 Flutter 内置本地化系统构建可适配多语言的软件。其核心目标是以 ARB 文件作为所有翻译的唯一数据源,避免硬编码文本,并正确处理不同语言与地区的布局差异。

主要能力与核心标准

技能要求将以下标准应用于所有国际化工作:

  • 绝不硬编码面向用户的字符串,所有文本必须经过 l10n 系统。
  • 使用 Flutter 内置本地化系统(flutter_localizations + intl),不使用第三方 i18n 库。
  • ARB 文件是所有翻译的唯一数据源。
  • 通过 BuildContext 扩展提供更简洁的 l10n 访问方式,使用 context.l10n 而非 AppLocalizations.of(context)。
  • 可复用组件通过参数接收本地化字符串,不将共享组件直接耦合到 AppLocalizations。
  • 使用 EdgeInsetsDirectional(start/end)替代 EdgeInsets(left/right),以确保 RTL 语言下布局正确。
  • 正确处理 RTL 布局,对 padding、定位和对齐使用方向性组件。
  • 尽早实施 i18n,即使初期只计划支持一种语言,其开销很小而长期收益显著。

技能还给出了关键术语定义:Locale(定义用户地区、语言及货币、时间、数字等偏好的属性集合)、Localization(l10n,通过翻译文本和添加地区布局使软件适配特定语言的过程)、Internationalization(i18n,设计软件使其无需工程改动即可适配不同语言的过程)。

使用方式

设置流程:添加 flutter_localizations 和 intl 依赖,在 pubspec.yaml 中启用 generate: true,配置 l10n.yaml,在 lib/l10n/arb/ 中创建 ARB 文件,运行 flutter gen-l10n,并在 MaterialApp 中配置 localizationsDelegates 和 supportedLocales。ARB 文件支持简单字符串、占位符和 ICU 复数语法。

BuildContext 扩展:创建扩展以在整个代码库中便捷访问 l10n,例如定义 AppLocalizationsX 扩展,提供 l10n getter 返回 AppLocalizations.of(this),使用时写 Text(context.l10n.helloWorld),避免写 Text(AppLocalizations.of(context).helloWorld)。

可复用组件策略:位于独立包中的共享组件不应直接依赖 AppLocalizations,而应通过构造函数参数传入本地化字符串。技能以 ConfirmDialog 为例,其接收 title、message、confirmLabel、cancelLabel 等字符串参数,在应用层调用时传入 context.l10n 对应的值。

文本方向性:所有 padding 和 margin 使用 EdgeInsetsDirectional(start/end)而非 EdgeInsets(left/right);对 RTL 感知布局使用方向性组件变体(PositionedDirectional、AlignDirectional、BorderDirectional)。图标在 RTL 下自动镜像,图片需要设置 matchTextDirection: true。

后端考虑:后端内容按语言存储翻译,并要求客户端传输用户 locale。对于错误消息,在前端将 HTTP 状态码或自定义后端错误常量映射到 l10n 键。

常见模式:

  • 新增语言:在 lib/l10n/arb/ 创建 app_<locale>.arb(如 app_fr.arb),为模板 ARB 文件中的所有键添加翻译,运行 flutter gen-l10n,新语言会自动通过 AppLocalizations.supportedLocales 可用。
  • 新增字符串:在模板 ARB 文件(app_en.arb)中添加键值对,按需添加带描述和占位符的 @key 元数据,在所有其他 ARB 文件中添加翻译,运行 flutter gen-l10n,通过 context.l10n.newKey 使用。
  • 复数处理:在模板 ARB 文件中使用 ICU 消息语法定义复数,提供 "type": "int" 的占位符元数据,在所有语言 ARB 文件中添加复数形式,通过 context.l10n.itemCount(items.length) 使用。

适用场景

适用于使用 Flutter 构建、需要支持多语言或多地区(包括 RTL 语言)的应用开发,尤其适合希望统一翻译管理、避免硬编码文本、并让共享组件保持与本地化解耦的项目。

限制

资料未提供该技能的具体安装命令、版本要求、收费或价格信息,也未提供 references/setup.md、references/directionality.md、references/backend.md 等参考文件的完整内容,相关细节暂未提供。