Convention for naming string keys for "tier 1" description features.

[pixelzoom]

After working on #82, it was difficult for me to see which strings were for accessibleName vs helpText vs something else. The naming convention that we use for visual strings keys really wasn't holding up. And it seemed like grouping strings by their associated UI component was more valuable here for development/maintenance, and potentially more useful to a translator.

So I experimented with a different structure for string keys in bb2447e.

UI components looks like this:

    "deBroglieRepresentationComboBox": {
      "accessibleName": {
        "value": "de Broglie Representation"
      },
      "helpText": {
        "value": "Choose the wave representation for de Broglie model."
      }
    },

Screens looks like this:

 "energyLevelsScreen": {
      "screenButtonsHelpText": {
        "value": "Explore electron transitions and relate observations to quantum models of the hydrogen atom."
      },
      "screenSummary": {
        "playArea": {
          "value": "The Play Area contains a light source aimed at a sample of hydrogen atoms. The observation window displays a zoomed-in view of a single hydrogen atom, which varies with the mode of exploration. In Experiment mode, the structure of the hydrogen atom is a mystery and is obscured. In Model mode, there are three quantum models of the hydrogen atom to explore. Determine the structure of the hydrogen atom by shining white or monochromatic light on the sample. Observe changes in the electron’s state in the Electron Energy Level diagram."
        },
        "controlArea": {
          "value": "The Control Area has a Spectrometer that displays a histogram of the photons emitted by the hydrogen atom. Take snapshots of the spectrometer data and compare up to four snapshots at a time. Control how fast the action happens in the observation window, including buttons to pause or step forward, and reset the sim."
        },
        "interactionHint": {
          "value": "Turn on the light source to start exploring."
        }
      }
    },

This sha for the entire strings file can be viewed at models-of-the-hydrogen-atom-strings_en.json, and the subsection under "a11y" is what's relevant.

This undoubtedly needs broader discussion. But since the structure of the strings file is mainly an implementation detail, I'd like to start by getting thoughts from @jbphet and @jessegreenberg.

[pixelzoom]

Btw... The keys used to identify UI components are the same as the tandem names - for example, deBroglieRepresentationComboBox, quantumNumbersInfoButton,... This makes it super easy for me to locate strings related to a PhET-iO elements. And I suspect that would also be valuable if we're going to require PhET-iO clients to change related strings in Studio. For example: If you needed to change the description strings associated with PhET-iO element deBroglieRepresentationComboBox, then you'd search for deBroglieRepresentationComboBox in the Studio tree, and you'd find deBroglieRepresentationComboBox.accessibleNameStringProperty and deBroglieRepresentationComboBox.helpTextStringProperty. And this would be consistent for all PhET-iO elements.

[terracoda]

I agree that "grouping strings by their associated UI component" or their place in the state description (e.g., Screen Summary-Play Area) is a valuable way forward. I think this can be helpful for many use cases, development, design and translation.

[jbphet]

I think it would be great to have some structure like this, but we've run into issue with it in the past because the strings files would get out of sync with the code. That's why we ended up on a "least common denominator" sort of solution where almost all of the string keys are at the top level of the structure and the value is close to the text. Here's an example of a key from the Greenhouse Effect sim. This is at the top level.

  "sliderAndFluxMeterControls": {
    "value": "Slider and Flux Meter Controls"
  },

So, my initial thoughts are that it would be great to have this, but we would also need tooling to support it that would verify that phet-io names, string keys, and file names are all staying in sync.

Also, FWIW, the structure of the string keys don't matter much to Rosetta (the translation utility), so there wouldn't be a big impact there.