Spike: Research and define strings handling in frontend

[infinitewarp]

We need to figure out how to put localized strings (including user-facing "docs" in tool tips) in our front-end client/application. Do some investigation about practices (best or not) for teams around us or like us. Does it make sense to have a separate "docs" git repo (CCS = "Customer Content Services")? Note that "all of RH docs live in a git repo" somewhere (Jamie knows something about this). Would frontigrade pull and build in the contents of that repo?

Output: Define a path for us with a proof of concept.

Time box: 3 days?

[cdcabrera]

Results

Basic repository layout

The formatting for strings, and possible documentation, hosted within an external Wordigrade level repository.

Appears we can leverage the basic structure of a NPM, with/without publishing, which is as simple as including a package.json file with the following minimal structure. More detail on NPM structure

{
  "name": "wordigrade",
  "version": "0.0.0",
  "description": "Lorem ipsum...",
  "author": "Red Hat",
  "license": "GPL-3.0",
  "private": true,
  "repository": {
    "type": "git",
    "url": "https://github.com/cloudigrade/wordigrade.git"
  }
}

From there releases plus tagging, and some level of semver help call out to the consuming repository(ies) what version is needed. Some level of semver should give the ability to roll back and pull from earlier versions if necessary.

The consuming repository, Frontigrade places a reference to Wordigrade within its own package.json file ...

• If NOT published to NPM

    "dependencies": {
      ...
      "wordigrade": "https://github.com/cloudigrade/wordigrade#0.0.0"
      ...
    }
  

• If published to NPM (also involves removing the private property from the Wordigrade JSON)

    "dependencies": {
      ...
      "wordigrade": "0.0.0"
      ...
    }
  

What does the structure of Wordigrade look like?

In order to optimize consumption through Frontigrade the basic directory structure of Wordigrade should have some form of a distribution directory...

Generic

  - package.json
  - .npmignore
  - README.md
  - LICENSE
  - [other directories and files... i.e. docs]
  - dist
    - locales.json
    - en.json
    - es.json
    - fr.json
    ... additional locales as necessary

More detailed

  - package.json
  - .npmignore
  - README.md
  - LICENSE
  - [other directories and files... i.e. docs]
  - dist
    - locales.json
    - en
      - en.json
      - [possibly some detail like tooltips-en.json]
    - es
      - es.json
    - fr
      - fr.json
    ... additional locales as necessary

Locales.JSON

In order to pull some basic information about the strings being consumed we're recommending a locales.json file be placed in the root of the dist/distribution directory. This file could contain a structure similar to the below. Where version indicates versioning around the translation/locale, or a more global repo level version, value and key being more obvious as descriptions.

Generic

{
  "locales": [
    { "version": "1.2.0", "value": "en", "key": "English"},
    { "version": "1.2.0", "value": "es", "key": "Spanish"}
    { "version": "1.2.0", "value": "fr", "key": "French"}
  ]
}

More detailed

This is a proposed format, not yet researched. The list format with nested objects should enable expansion if additional properties, such as details needed to be included at some point.

{
  "locales": [
    { "version": "1.2.0", "value": "en", "key": "English", "details": ["en.json", "tooltips-en.json"]},
    { "version": "1.2.0", "value": "es", "key": "Spanish", "details": ["es.json"]},
    { "version": "1.2.0", "value": "fr", "key": "French", "details": ["fr.json"]}
  ]
}

This should enable consumer convenience to list, without having to scan resource files, what locales are being provided.

[cdcabrera]

As an additional aspect to documentation. Patternfly itself already has a pattern for a "tour", see

• http://www.patternfly.org/pattern-library/communication/tour/
• http://www.patternfly.org/pattern-library/communication/tour/#design

Utilizing this component for integration with help documentation, combined with locale key/value pairs, would fit within a pre-defined UX/UI experience.

@bclarhk