C2LC-228: Rationalise the localisation of command names

Description

From Simon’s notes in the technical debt Google doc.

In preparing a build of the coding environment to demo for the Closing The Gap 2020 presentation, we wanted to change the name used in the UI for the “forward” command to “move”. See https://issues.fluidproject.org/browse/C2LC-217

In making this change I noticed some issues with how we are localising command names:

The localised name for the “forward” command had to be changed in multiple places
There were places in the code that did not use a localised name for commands, but rather used the name from the program directly

The changes needed for the CTG 2020 rename of “forward” to “move” can be seen in these commits:

https://github.com/codelearncreate/c2lc-coding-environment/commit/2af9f10674caeb72a7448ee117a3600f67929f87
https://github.com/codelearncreate/c2lc-coding-environment/commit/4196aaaf064fe17d95d7272c3b7b0377ab3ecb97
https://github.com/codelearncreate/c2lc-coding-environment/commit/4dd46f62d305bdd156ad65295ad951eb38e9388b

We should rationalise our localisation of command names so that:

  1. There is a single point where localised names are specified
  2. All usage of command names in the UI is localised

Comments

  • Tony Atkins [RtF] commented 2020-09-24T07:33:36.561-0400

    Quick note from my review of the code. There are usages of raw strings in tests, which doubles the amount of work when making wording changes. In some tests, we simply retrieve the message and compare that, as in:

    expect(img.prop('aria-label')).toBe(intl.messages['DeviceConnectControl.connecting']

    We want to be able to test that all of a message’s variables are wired up correctly and that there are no other integration issues (such as failing to pass on the formatted message from a parent component).

    For all strings that lack variables, we’re mainly testing for integration issues that would prevent the message from being available to the component. For those I think it’s fine to compare the expected output to the literal message.

    For messages with variables, we can either keep using raw strings, or format the expected message ourselves and compare that. On balance I’d argue for continuing to use raw strings, as it ensures that we’re not comparing badly formatted and meaningless text to the same badly formatted and meaningless text.

  • Tony Atkins [RtF] commented 2020-09-24T08:21:11.858-0400

    So, one thought I had was to compose messages using other messages, i.e. to reuse a common wording for “forward”/“move” in all the places it appears. I couldn’t find a clean way of doing this with react-intl or the various libraries it depends on. The closest I could think of is to expose the locale messages as a value, so that we could use syntax like:

    "CommandInfo.nextStep.forward": "after Step {nextStepNumber} {messages['CommandInfo.forward']}",

    This approach was frustrated by the fact that only shallow objects are supported. We can work around this by flattening the object using dashes as a separator, but that way lies madness.

    Given that, I was thinking one strategy is to use some kind of multi-pass system where we resolve the formatted text for the pieces (“Forward”, etc.) and pass those through a second time to come up with the final text.

    Even if we could get the first approach working, both approaches are blocked by the lack of support for simple capitalisation in react-intl, as we need to have both lower case “forward” and title case “Forward”.

    I think it would make sense to briefly look at other i18n frameworks that work well with React to see if there are better options, something equivalent to partials in handlebars or some other way of reusing messages in other messages.

  • Tony Atkins [RtF] commented 2020-09-24T08:30:45.131-0400

    i18next does at least support deep object references:

    https://www.i18next.com/translation-function/interpolation

    It also supports formatting as part of the template:

    https://www.i18next.com/translation-function/formatting

    Critically, it also supports nesting of messages:

    https://www.i18next.com/translation-function/nesting

  • Tony Atkins [RtF] commented 2020-09-24T08:35:44.742-0400

    LinguiJS seems lighter weight than react-intl, but lacks the key features we need, i.e. rudimentary formatting and nesting of messages.

  • Tony Atkins [RtF] commented 2021-02-25T09:56:28.566-0500

    We agreed that this was taken care of when we merged C2LC-243.