How we make multilingual atproto records? - Adam Mika

I haven't found any conventions (or best-practices) yet for how to work with multilingual records within atproto, so I'm sharing how we approach it when designing our own lexicons (they're not public yet). We took inspiration from the app.bsky.* lexicons themselves and added the style we use in classic RESTful/GraphQL APIs.

For example, this is my lexicon entry id.sifa.profile.self:

{
  "uri": "at://did:plc:fytfkwmlpcdxoqtrbzaorspt/id.sifa.profile.self/self",
  "cid": "bafyreibovp2javpyeq74z6xn4x7sgmymcs55dinrbjss5daquatkn3ok54",
  "value": {
    "$type": "id.sifa.profile.self",
    "about": "...",
    "openTo": [],
    "headline": "Průzkumník (Pioneer) s částečným přesahem do Vesničana (Villager)",
    "createdAt": "2026-07-25T19:31:21.201Z",
    "givenName": "Adam",
    "familyName": "Mika",
    "preferredWorkplace": []
  }
}

We always try to save the record with the optional langs parameter, which Bluesky also uses in its lexicons:

{
  "uri": "at://did:plc:fytfkwmlpcdxoqtrbzaorspt/id.sifa.profile.self/self",
  "cid": "bafyreibovp2javpyeq74z6xn4x7sgmymcs55dinrbjss5daquatkn3ok54",
  "value": {
    "$type": "id.sifa.profile.self",
    "about": "...",
    "openTo": [],
    "headline": "Průzkumník (Pioneer) s částečným přesahem do Vesničana (Villager)",
    "createdAt": "2026-07-25T19:31:21.201Z",
    "givenName": "Adam",
    "familyName": "Mika",
    "preferredWorkplace": [],
    "langs": ["cs"]
  }
}

And if we need the record to be available in other languages, we add an optional translations object, which can contain translated values of fields that make sense to translate:

{
  "uri": "at://did:plc:fytfkwmlpcdxoqtrbzaorspt/id.sifa.profile.self/self",
  "cid": "bafyreibovp2javpyeq74z6xn4x7sgmymcs55dinrbjss5daquatkn3ok54",
  "value": {
    "$type": "id.sifa.profile.self",
    "about": "...",
    "openTo": [],
    "headline": "Průzkumník (Pioneer) s částečným přesahem do Vesničana (Villager)",
    "createdAt": "2026-07-25T19:31:21.201Z",
    "givenName": "Adam",
    "familyName": "Mika",
    "preferredWorkplace": [],
    "langs": ["cs"],
    "translations": [
        { "langs": ["en"], "about": "...", "headline": "Pioneer with partial overlap into Villager" }
    ]
  }
}

I would be grateful for feedback and discussion so that we can ideally be consistent within the network.