JSON-LD language maps for "preferredUsername"?

[reiver]

ActivityPub/ActivityStreams already supports JSON-LD language maps for the "content", "name", "summary" fields.
This makes it easier to use ActivityPub/ActivityStreams in multi-language situations.

One example of this includes simultaneously including the same text in multiple languages:

"nameMap": {
  "en": "Hello world",
  "fa":"درود جهان",
  "fr": "Bonjour le monde"
}

Another example of this is to indicate the language of a single field value:

"nameMap": {
  "fa":"درود جهان",
}

...

Currently ActivityPub/ActivityStreams does not support JSON-LD language maps for the "preferredUsername" field.

If ActivityPub/ActivityStreams supported JSON-LD language maps for the "preferredUsername" (i.e., preferredUsernameMap) then it, too, could be used in multi-language situations.

For example:

"preferredUsernameMap": {
  "en": "hello",
  "fa": "درود",
  "ko": "안녕하세요"
}

...

At FediForum in April 2026 there was (yet again) discussion over supporting user-names in non-latin alphabets.
There was also discussion about it at FediCon 2025.

[trwnh]

What's the value of language-tagging the preferredUsername? Language tagging is a completely separate concern than the use of non-Latin alphabets.

This is already fine:

"preferredUsername": "안녕하세요"

I'm curious to know about a processing context that cares about the @language of this @value.

We don't explicitly say that there can only be one preferredUsername, but the processing of a "preferred username" is to suggest or auto-claim usernames when signing up for new services. https://datatracker.ietf.org/doc/html/draft-smarr-vcarddav-portable-contacts-00

nickname:
The casual way to address this Contact in real life, e.g. "Bob" or "Bobby" instead of "Robert". This field SHOULD NOT be used to represent a user's username (e.g. jsmarr or daveman692); the latter should be represented by the preferredUsername field.

preferredUsername:
The preferred username of this contact on sites that ask for a username (e.g. jsmarr or daveman692). This field may be more useful for describing the owner (i.e. the value when /@me/@self is requested) than the user's contacts, e.g. Consumers MAY wish to use this value to pre-populate a username for this user when signing up for a new service.

It's something of a historical peculiarity that preferredUsername got adapted into AP and used for constructing an acct: URI to stuff into WebFinger. In any other usage, you could imagine having multiple preferred usernames, perhaps even an ordered list of preferred usernames which get tried in order, and if one isn't available, then you move on to the next one. Kind of like how in an IRC client, you can set your "preferred username" when joining an IRC network, and many IRC clients will let you specify a list of usernames to try in case your more-preferred usernames are already taken. (The IRC network's NickServ can also resolve any conflicts by whatever strategy it supports; for example, it might append "1" or "2" or so on depending on other connected usernames.)

Unless there's a useful reason to language-tag this property, I think the better approach is to follow #576 instead and simply note that Unicode is allowed, and maybe recommend that consumers SHOULD be prepared to accept Unicode here.

[reiver]

The same Unicode string can look different depending on the language.
For example, with Arabic, Persian, and Urdu.

Whether a user-name (or any other word) is rendered Naskh style or Nastaliq style depends on the language choice.

So, same Unicode string for the user-name, but different rendering depending on the language.

[tesaguri]

The topic has previously been discussed in #395, which proposed the removal of the mention of natural language map support for preferredUsername in the spec. But I think the problem of glyph selection has not been considered in that issue (I should have come up with that point then since my native tongue is also affected by it like on a daily basis.)

That said, if the current practice is to treat preferredUsername as acct: URI username and canonise it via WebFinger, I think we would not (only) need a support for language tag in preferredUsername, but in JRD subject.

[trwnh]

JRD subject having a language tag feels like we might be getting mixed up here. You test for exact string matching based on Unicode codepoints, and the JRD format doesn't have a built-in way to render that subject as text.

I guess what this comes down to is whether preferredUsername should ever be rendered as text, separately from name. This seems like a yes if you take Mastodon's usage into consideration, but that could be deceptive, so more careful consideration is needed to tease apart the concerns.

It looks like Steve closed #395 along with other issues at around the same time, but I think #395 should be reopened and/or considered alongside this issue.

One other aspect of language-tagging usernames is that the language may differ from the domain. So language-tagging a JRD subject might not be so straightforward.

Also, the xMap pattern in AS2 isn't necessarily the most appropriate here. If we decide that order matters and there is a value for preferredUsername that is a @list, then we might get something like this:

"preferredUsername": {"@list": [
  {"@value": "안녕하세요", "@language": "ko"},
  {"@value": "hello", "@language": "en"}
]}

The way this gets processed could be to try the Korean-tagged value first, and then if the consumer doesn't support that username for some reason, it would try the English-tagged value second.

If a consumer expects only one preferredUsername and only wants the language-tagging information, then it could look like this:

"preferredUsername": {"@value": "안녕하세요", "@language": "ko"}

...which would require consumers to parse @value as a JSON object and not simply as a JSON string.

Another pattern which is possible (but comes with its own problems) is to do something like how as:mediaType applies to as:content (but defaults to text/html if missing, and is otherwise ambiguous with its application to as:href on some as:Link).

[evanp]

I think we should concentrate on what we want to get out of this. Is the goal to provide an alphanum-only username and one that isn't alphanum-only? Or do we expect to have 3 or more language variants in this property?

If the goal is alphanum/non-alphanum, I think we should just define another property for the alphanum-only value. If we want to support multiple languages, I think preferredUsernameMap is the way to go.

We used to have a reference to the *Map variant of preferredUsername in the published version, and removed it in the errata because it was not actually defined!

[trwnh]

do we expect to have 3 or more language variants in this property?

Even with only 1 value in the set, language tagging might be useful for text rendering. The data would look like this (the following codeblocks are equivalent if preferredUsernameMap is defined similarly to other xMap properties in AS2):

"preferredUsername": {"@value": "안녕하세요", "@language": "ko"}

"preferredUsernameMap": {
  "ko": "안녕하세요"
}

I believe what @reiver is describing is the unexpected/incorrect text rendering that can occur when certain Unicode graphemes are not language-tagged:

It's something that people can work around with OS-level hacks, like https://wiki.archlinux.org/title/Font_configuration/Examples#Excluding_Arabic_script_from_other_languages describes. But the proper fix is usually to language-tag the string, because including a language tag causes the correct font to be selected.

But also, this is a concern of "text rendering", and not "using the username to construct an acct: URI" or any sort of uniqueness constraint.

[reiver]

Just thinking out loud....

Another approach, that would make this more friendly to people who want to access fields in a more JSON way (rather than JSON-LD way) would be —

№1:

Keep preferredUsername the way it is,and

№2:

Add a preferredUsernameLanguage field.

...

That would deal with the situation where the same Unicode string get rendered differently depending on the language the Unicode string is in. (I.e, Arabic, Persian, and Urdu issue.)

[trwnh]

@reiver A preferredUsernameLanguage field presupposes that there is at most exactly 1 preferredUsername, or that they all share the same language. We actually have this class of issue with mediaType being applied to content (as opposed to href). There might be more than one value for content, and it's unclear what to do if content happens to differ in content-type between languages. In other words, we implicitly assume that nothing like this will ever happen:

"content": [
  {"@value": "<em>Hello!</em>", "@language": "en"}, // implicit text/html
  {"@value": "**Hello!**", "@language": "en"} // implicit text/markdown
]

Which is to say, if we draw an rough analogy to HTTP, we allow the Content to Vary by the Content-Language but not the Content-Type (or any other dimension like Content-Encoding etc).

These two content values convey the same semantics when parsed according to the semantics of their (implicit) media type, but that's not obvious at the level of the container (the JSON-LD document).