PAYATHON 2026

Square In-App Payments SDK 本地化 ZIP 字段

支付阿杰

结论

在存在这一问题的 In-App Payments SDK 版本中,无法通过 en_GB、SQIPTheme 或公开 API,将内置卡片录入界面的“ZIP”改为“Postal”。这不是配置缺失,而是 SDK 没有开放该字段的本地化设置。

SQIPTheme 只能调整颜色、字体等视觉样式,不能修改字段标题或占位文本。

为什么设置英国区域仍然无效

将设备语言或区域设置为 en_GB,不代表 SDK 中的所有文字都会自动改用英国英语。SDK 必须提供相应的本地化资源,并在运行时读取这些资源,“ZIP”才有可能自动显示为“Postal”。

如果当前 SDK 将这段文字固定为“ZIP”,修改以下设置也不会生效:

Locale.current
<key>CFBundleDevelopmentRegion</key>
<string>en_GB</string>

也不建议修改 AppleLanguages、遍历内部视图,或通过 Key-Value Coding 强制替换文字。这些做法依赖 SDK 的私有实现,升级后很容易失效,还可能影响审核和无障碍功能。

可行的处理方式

可以先升级到项目支持的最新 In-App Payments SDK,并查看该版本的官方本地化说明。不同版本支持的功能可能不同。如果新版已经加入英国英语资源,SDK 会根据其支持的语言和区域自动显示对应文案,不需要通过 SQIPTheme 设置。

如果升级后仍显示“ZIP”,说明公开接口依然不支持修改该名称。较稳妥的处理方式是在付款表单附近为英国用户补充说明,例如:

let postalCodeHintLabel = UILabel()
postalCodeHintLabel.text = "ZIP refers to your billing postcode."
postalCodeHintLabel.numberOfLines = 0
postalCodeHintLabel.font = .preferredFont(forTextStyle: .footnote)
postalCodeHintLabel.textColor = .secondaryLabel

这样既不需要修改 SDK 的内部控件,也能让用户知道这里应填写账单地址的 postcode。

是否可以关闭内置字段

部分 SDK 版本提供 collectPostalCode 配置。如果当前版本确实公开了这个属性,可以关闭内置字段:

let cardEntryViewController = SQIPCardEntryViewController(theme: theme)
cardEntryViewController.collectPostalCode = false

然后在自己的界面中使用英国用户更熟悉的名称:

let postcodeTextField = UITextField()
postcodeTextField.placeholder = "Billing postcode"
postcodeTextField.textContentType = .postalCode
postcodeTextField.autocapitalizationType = .allCharacters
postcodeTextField.autocorrectionType = .no

但这并不只是替换文字。自行输入的 postcode 通常不会自动写入 SDK 创建的卡片 nonce,也可能无法用于地址验证。关闭内置字段前,需要确认以下事项:

  • 当前 SDK 版本确实支持 collectPostalCode。
  • 商户所在地区和支付流程不要求 SDK 收集邮政编码。
  • 服务端支付请求不依赖该字段进行地址验证或风险控制。
  • 自行收集和传输账单地址符合 PCI、安全及隐私要求。

如果邮政编码必须随卡片信息提交给 Square,通常更安全的做法是保留 SDK 的内置字段,并在旁边补充 postcode 说明。

注意事项

不要直接修改 SDK bundle 中的字符串资源,也不要依赖内部 UITextField 的视图层级来替换 placeholder。这些内部实现没有兼容性保证。

如果新版 SDK 没有提供官方本地化支持,就无法通过公开 API 将内置的“ZIP”直接改为“Postal”。可选的做法只有三种:升级 SDK;保留内置字段并补充 postcode 提示;或者在确认支付和合规影响后,关闭内置邮编收集并自行设计输入流程。

备注:内容仅供参考。