15 August 2026: preferred language scope Developer

Last updated Aug 15, 2026

15 August 2026: preferred language scope

Update date: 15 August 2026

Swaymoon Account now lets users set a preferred language. App identifiers can request the field scope locale and read that preference on the authorization callback.

Compatibility

Existing production clients do not need code changes or a new release because of this update. If you do not request locale, behavior is unchanged.

If you localize UI or email by user language, add locale on the identifier in the Developer portal (optional or required).

Summary

Users set a preferred language on Account → Personal Information: zh-CN, zh-TW, en, or ja.
New profile field scope: locale, matching the UserInfo / ID Token claim locale (BCP 47).
When locale is granted, both the ID Token and UserInfo include the claim, so the authorization redirect callback can read it without an extra UserInfo call.
When it is not granted, UserInfo still returns an empty-string placeholder and does not leak the real preference.
New identifiers include locale as optional by default. Existing identifiers must opt in on the portal Features step.

See Scopes and consent and Tokens and user info in the parent directory for the claim table, and the Account guide Personal Information for the user-facing field.

What you should do

Situation	Suggestion
You do not need the user’s language	No change. Leave existing clients as they are.
You localize by language	Edit the identifier and set `locale` to optional or required (required needs a reason and a privacy policy). Read `locale` from the ID Token or UserInfo, and use token `scope` to tell whether it was granted.
Do not treat placeholders as real preferences	A `locale` that is not in `scope` is an empty string meaning not granted, not “the user left it unset”.

SMS verification codes stay Simplified Chinese and do not follow preferred language.

Doc URLs

All four languages share the same English URL path, for example:

https://docs.swaymoon.com/en/view/swaymoon-developer/guides/identifiers/scopes-and-consent?developer=true
https://docs.swaymoon.com/zh-CN/view/swaymoon-developer/guides/identifiers/scopes-and-consent?developer=true

Older Chinese paths redirect to these English paths.