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

seanforyou23 commented 6 years ago

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.

API Endpoints and Schemas

doc/tooltips/tooltips.json

Tasks involved / Steps to Reproduce

Move hard coded tooltip text into doc/tooltips/tooltips.json and negotiate key names with @TovaCohen
Use mvn plugin tooling to generate tooltips.json so DOC folks then have finite control
Repeat this process for all site text, beyond just tooltips
Confirm what languages/locals we intend to support
Make a decision on whether or not we intend to support RTL languages
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.

TovaCohen commented 6 years ago

This looks great! I can't think of any details you missed. I'm really glad the long-term plan is extract all text in the UI from the doc source files.

deeleman commented 6 years ago

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

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.
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.
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.

seanforyou23 commented 6 years ago

Great points @deeleman, it's been a while since I implemented translation dictionaries, and last time I did it was in a multi-page application so I'm sure techniques have changed a bit since then :) Given your experience and interest in this, I'd like to work with you more on the actual UI implementation to ensure it's built well fashioned.

The tooltips.json is just stepping stone toward this bigger goal. So not suggesting multiple documents for different kinds of text, just a single document in the many supported language/local combos as you described above. So tooltips.json will likely become text-content.json or something of the sort.

Here's an example of a well structured translation document - just for reference https://cdn.karjalakasino.com/dictionaries/en-gb.json

Anyway, good to know we have some direction for implementation!

TovaCohen commented 6 years ago

Just want to note here that I discussed this with some of the other Fuse writers today. Maybe the better solution is simply for a doc person (just me for now) to directly update the product source files. This is open source, right ? :-) The original premise was that text in the UI duplicates text in the guides we provide. But in reality, it is rare that text in the doc source is the exact text that we want in the UI. So, after GA, let's talk before anyone does any more work on this.

deeleman commented 6 years ago

Maybe the better solution is simply for a doc person (just me for now) to directly update the product source files.

Would you feel comfortable editing the texts in a JSON file? I think it is the best way forward.

With this being said, I self-assign this issue to myself. Hopefully will get a POC or even the entire site localized in a couple of days.

TovaCohen commented 6 years ago

I am not in today but I am definitely comfortable editing Json files and I already requested two PRs that were merged for the FTP and drop box connectors so please do not do a lot of work here. I definitely think that the better solution is for me to edit the source strings directly

TovaCohen commented 6 years ago

Just want to note here that I talked with Michael S. about the feature Pablo coded and I am all for the dictionary json file. I can edit that file instead.

deeleman commented 6 years ago

@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 :)

syndesisio / syndesis