Update structure of translation files for the Reference section

[yukienomiya]

See PR #803

Background

• Problems with the existing Reference translation files structure:

  • Params - The parameter elements are currently saved in arrays of strings, where each element has a "paramType: paramDescription" structure. They are then inserted in the translated webpage in the order in which they were saved. This is problematic because every little edit on the webpage could mess this order up (here for example, the descriptions of the "colorstring" param and the "a" param are switched).
  • Description - In the original documentation, the description text is split into paragraphs. This is especially important in long descriptions -Classes' for instance- because it helps with the text's legibility.
    In the translated JSONs the descriptions were saved as single strings and therefore displayed on the website as single paragraphs.
  • Classes - Some of the p5 Classes in the JSON files are saved as nested objects in the p5 Class object (i.e., the p5.Shader Class in the es.json). The text from those classes isn't swapped by the updateLanguage() function.

• The updateLanguage() function that is supposed to swap English text in Reference pages with its translation, currently only translates method/fields pages: the swap doesn't work in Class pages, so for example, even if Class descriptions are translated in the JSON files, the translation is never rendered on the webpage.

Changes:

• Convert existing translation files to new format:

  • Parameter elements saved by their name. (Changes made by @outofambit in the PR Convert exisiting translation files to new format #835.)
    Save the "params" elements as object, where each element has a "paramName": "paramType: paramDescription" structure.

  • Description elements: from strings to arrays of strings.
    Convert the descriptions elements from strings to arrays of strings, where each array element represents a paragraph. This change won't make much difference with the already translated descriptions, as they are saved as a single paragraph, but the structure change will be useful when we'll add the rest of the documentation.

  • Move Classes out of the p5 Class object, to match new format.

• Update the updateLanguage() function:

  • Add script section that swaps text from Class pages of the Reference.

  • Modify the script so it matches the new Reference JSON structure.

New structure of the Reference JSON files:

[limzykenneth]

I haven't been following this project very closely so sorry if my question is a bit basic or already answered. By "reference JSON files" do you mean these files will be used instead of data.json to render the reference, choosing the relevant language or would the es.json and zh-Hans.json be used in the website for the translation swapping?

I've mentioned in another issue before that I've been looking at new tools to generate reference data from the inline documentation and the structure you layout here is very helpful in that sense since if a schema defined I can use comment-parser that I've been experimenting to extract the relevant data from comments and populate it according to the schema you have here. An example of how I'm using it is here

There are several ideas that I think I can build on after this project is merged and a schema that defines how the reference data is defined would be a big part of it.

[yukienomiya]

@limzykenneth By "Reference JSON files" I mean the JSON files used for the translation swapping (es.json, zh-Hans.json...). I'm not making any changes in that sense, so the data.json will still be used to render the English version of the website and the JSON files (es.json, zh-Hans.json...) will be needed for the translation swaps.

The need for a defined structure stems from the fact that I created a script that generates the English version of the JSON files, the en.json (see PR #837), so I needed to make sure they all shared the same structure. This is important in order to be able to compare the English version with the translation JSON files and to keep them constantly updated.

[yukienomiya]

I've mentioned in another issue before that I've been looking at new tools to generate reference data from the inline documentation and the structure you layout here is very helpful in that sense since if a schema defined I can use comment-parser that I've been experimenting to extract the relevant data from comments and populate it according to the schema you have here. An example of how I'm using it is here

So if I understand that correctly, the output of the comment-parser would be used to both render the Reference section of the website and as a model for other translations (the file to duplicate when starting a new translation)?

[limzykenneth]

The ideal solution that I can come up with is to use comment-parser to end up with en.json in one step then use en.json to render the reference instead of using data.json. Following your work here, en.json, es.json, zh-Hans.json and future translations should share the same JSON structure so instead of the swapping mechanisim, we can actually render the reference with the relevant JSON file directly.

The translation workflow you setup here will also work nicely with it.

[yukienomiya]

@limzykenneth I agree, rendering the website with the translation files would definitely make more sense.
With the PR #308 I tried to bridge the gap between the structures of the data.json and the other translation JSONs by introducing the en.json. I guess we could use it anyway until your solution gets implemented and the data.json becomes deprecated.

[limzykenneth]

I'll see if I have some time to update reference rendering once the two PRs are merged.

[lmccart]

I don't think this is the correct spot, but I wanted to mention that we have some of the p5 classes translated into spanish in this doc. We didn't add them into the translation files yet because we weren't sure where they should go, but hopefully it's easier to loop them in with this new structure! @montoyamoraga

[yukienomiya]

@lmccart That's perfect! I can add them in once I bring all the translation files up to date with the English version (meaning I add all the missing keys to the translation files). -the PR with the script that does this is coming very soon 🙃

[outofambit]

Thank you @yukienomiya! I'm excited to merge this :)

I'll wait another 24 hours first just in case someone hasn't had a chance yet to share concerns or questions they might have.

[montoyamoraga]

@yukienomiya thank you!
i didn't remember that doc @lmccart,
happy to help port it to the website or proofreading it :)