Remove hard coded strings from UI and extract from doc source files instead

This is a…

[x] Feature request
[ ] Regression (a behavior that used to work and stopped working in a new release)
[ ] Bug report  
[ ] Documentation issue or request

The problem

The problem is that currently all of the text used within the UI is hard coded in template/controller files. This blocks us from doing two important things

1. Driving tooltip text from the actual docs as made possible in https://github.com/syndesisio/syndesis/pull/1369

2. Supporting internationalization and localization

This issue is an evolution of https://github.com/syndesisio/syndesis/issues/295, and is meant to encompass all the site text, and not just tooltip content. Having all the language used in the site scattered across many files makes updating text time consuming and difficult.

Expected behavior

The UI should never use literal text strings, but instead use a mechanism (probably a language service) that allows one to specify string keys, which in turn generate the appropriate text at runtime.

This will help improve consistency of the language used within the app and also speed up time required to update text on the site by moving power of control over to those who should have it in the first place.

Related Issues

https://github.com/syndesisio/syndesis-documentation/issues/20 https://github.com/syndesisio/syndesis-documentation/issues/23 https://github.com/syndesisio/syndesis/issues/295

API Endpoints and Schemas

doc/tooltips/tooltips.json

Tasks involved / Steps to Reproduce

1. Move hard coded tooltip text into doc/tooltips/tooltips.json and negotiate key names with @TovaCohen
2. Use mvn plugin tooling to generate tooltips.json so DOC folks then have finite control
3. Repeat this process for all site text, beyond just tooltips
4. Confirm what languages/locals we intend to support
5. Make a decision on whether or not we intend to support RTL languages
6. Address styling issues that come up, for example German translations are often much longer character strings than their English counterparts. The UI may not currently handle this flawlessly.

I can see number 3 above becoming quite a large work item, so it may make sense to turn this into an Epic and break the task down into more manageable chunks. I’ll let someone else make the call as to how best we can divide up this work.

[deeleman]

@TovaCohen I’m putting together a comprehensive tutorial about how to manage text strings through the dictionary file with guidelines for both content editors and frontend developers about how to approach and take advantage of this implementation. I’ll merge it today, so I’d recommend everyone involved in this endeavor to hold off before editing the master dictionary files. Thanks 😃

[deeleman]

Regarding steps [1] and [3], we should store all dictionary entries in a single JSON file. There’re several arguments for that:

1. Once we move all i18n strings to dictionary files, loading each file separately will clash against the limitations of browser’s XHR multiplexing, which is shared across ALL Js, media, CSS files being downloaded each time. Scattering text definitions across multiple files will turn into a huge loading bottleneck.
2. Key strings will be shared across files, so we better merge everything together in a single file so we can share the same key across different text locations.
3. I18N embraces the idea of text recursion. This is: dictionary entries containing other dictionary entries that can be projected recursively, to prevent issues generated by particular grammar divergences between languages, so we can smartly spare text entries. Eg:

en-gb.json

{
  integration: "Integration",
  brand: "Syndesis",
  uses: "This {integration} has been used {0} times in the {brand} application."
}

This renders: This Integration has been used X times in the Syndesis application.

es-es.json

{
  integration: "Integración",
  brand: "Syndesis",
  uses: "Esta {integration} ha sido utilizada {0} veces en la aplicación {brand}."
}

This renders: Esta Integración ha sido utilizada X veces en la aplicación Syndesis.

Please notice the divergences between placeholder lcoation. You get the drill… Please also notice how we will want to inject the X amount of uses dynamically.

The above can only be accomplished when handling a single file. Otherwise we might run into racing conditions. In regards of implementation from an UI POV, we will want to provide:

• An Angular service that fetches and exposes an asynchronous, observable dictionary.
• An Angular impure pipe that allows to parse dictionary keys and return the digested key, provided extended support for additional parameters injected on runtime.
• Optionally, a polyfill of the [innerHtml] attribute in the form of a directive that wraps syntactic sugar around said attribute to avoid having to use the aforementioned pipe inside that attribute.

I have already developed an implementation of all the above, and am just waiting for clearance, 3 working days and a working environment to get this done.