Conventions for naming keys for strings related to description

[pixelzoom]

Related to https://github.com/phetsims/models-of-the-hydrogen-atom/issues/67 and https://github.com/phetsims/scenery-phet/issues/876 ...

For strings that appear in the UI, PhET's convention is to use the English string as the string key. Some typical examples, from MOTHA:

  "billiardBall": {
    "value": "Billiard Ball"
  },
  "bohr": {
    "value": "Bohr"
  },
  "brightness": {
    "value": "Brightness"
  },
  "classical": {
    "value": "Classical"
  },
  "classicalSolarSystem": {
    "value": "Classical Solar System"
  },
  "deBroglie": {
    "value": "de Broglie"
  },
  "electron": {
    "value": "electron"
  },

For description-related strings, it's not clear if this convention is still appropriate.

In MOTHA, where description strings live under ModelsOfTheHydrogenAtom.a11y, I feel that the UI convention is NOT appropriate for strings related to accessibleName and helpText -- there is not enough information about the string's context. So I experimented with adding a "HelpText" suffix, like this:

 "a11y": {
    "absorptionAndEmission": {
      "value": "Absorption and Emission"
    },
    "absorptionAndEmissionHelpText": {
      "value": "Show Absorption and Emission dialog for electron state transitions and their associated wavelengths."
    },
...

This still does not feel sufficient for the ModelsOfTheHydrogenAtom.a11y approach. And it's hard to know what will be sufficient until decisions are made about how translation will be supported for description.

In any case... Conventions for naming string keys should definitely be a discussed.

[pixelzoom]

@jessegreenberg and I discussed this one. Before description strings are publicly released for translation, it's important to have conventions for string keys -- they are almost impossible to change later. Until we know when and how description translation is going to be done, we don't know if this issue is blocking for the MOTHA 1.0 release. My crystal ball says that we will be ready to release MOTHA 1.0 before PhET has a description translation solution, and that we should therefore leave the description strings "as is", under the "a11y" grouping where they are not visible in Rosetta, and can be changed in the future.

[marlitas]

Meeting 11/1/24:

• Discuss and determine naming convention between static and dynamic strings
  • Some "static" strings may have dynamic components (ex. MSAB "Ball at {{value}}"), but is simple enough to not require special dynamic string attention
  • Perhaps "simple" a11y?
  • Meet to discuss and decide on a convention that could work for this.
• Assigning to @jessegreenberg for next steps.