Rxjs: Translation on the docs

[niklas-wortmann]

For the rxjs docs we wanted to have translations for quite a long time.
I think I have an idea of a techinal approach that's feasible.

1. First of all we have the static content. This includes everything inside /docs_app/content. For supporting i18n, I would copy those file to according folders. E.g. for the german translation I would create a folder called de there and add all the files below. The folder structure is currently refering to the url anyway therefore our url schema would change from https://rxjs-dev.firebaseapp.com/guide/observable to https://rxjs-dev.firebaseapp.com/de/guide/observable. I could imagine that we maybe have to do some minor changes to the index.html and how it is loaded for now, because this approach would include a whole new index.html for each language.

2. Using the path for referring to the language is also good for seo and accessibility. Accessibility- wise we have to keep in mind to update the language attribute of the html tag accordingly to the url.

3. The parts generated from the source code are the tricky part IMO.

3.1. The API docs are autogenerated
The API Docs are auto-generated from the TSDoc comments inside the source code. Dgeni enables us to add custom annotations. Therefore I would create a custom annotation handling the translation logic.
E.g. such an annotation could look like @translation de - /docs_app/i18n/de/observable. This annotation would include the language so that the generated json could be stored accordingly. Additionally I would add a reference to the file to offer a bit a flexibility. The content of the refered file would be in tsdoc format but translated. The only problem I see for now with this approach is that we can just document one property in one file. This is a thing we have to figure out during development in my opinion.
Doing it in this way also offers the possibility to check if every file that is generated for the english language is at least also existing for all the other supported languages. Additionally we could also add a fallback behaviour, e.g. one operator isn't translated to german and therefore we display the english version of this operator. The only thing we have to keep in mind with doing so would be that we have to add an language attribute to one of the container element for accessibility purposes.

3.2. The deprecation
I don't have a very good approach for this ofr now. But maybe this is a thing only supported in the english version.

3.3. The "Choose your own operator" widget (open pr)
Pretty much the same like 3.2.

This approach in general doesn't bload the rxjs source code that much because there were just the added translation annotations.

In general I think point 1 and 2 are relatively easy to implement. Point 3 is definetly more complex but still I think it's feasible.

This Issue is also targeting #3814

Is there anything I missed for now?
I really appreciate any ideas/suggestions/feedback!

[ladyleet]

Okay very exciting to start chatting about this more. Thanks all for chiming in.

[niklas-wortmann]

Also we could think about externalize the dgeni and @translation part for providing that feature to angular and ngrx . I'm not sure if that easily do-able

[petebacondarwin]

I would avoid putting the @translation tags into the original source. Imagine how the source code would look if you were supporting 30 language translations!

I think it would be better to keep this out of band: either a separate configuration file or a convention.

Note that every document in dgeni has a unique id. So you could have a folder for each translation, and inside that folder have a file for each doc whose filename is the id of the doc being translated. It would be fairly easy for dgeni to intercept docs when they are being processed and looking in the translation folder for alternative translated text instead.

The really difficult bit is ensuring that the translations are kept in sync with the original source. I could imagine some script that parses commits for docs changes and then generates issues on GH for each translation??

[niklas-wortmann]

Thanks for the input pete. I really like the convention over configuration approach so I would tend to use that one.

I think the improvement about creating an GH issue directly would be cool but nice to have. I think the merge request for rxjs were merged by 3 to 8 people and being aware of the affecting changes should be fine, as a starting point. At the very beginning I would add some kind of hint to the translated versions that it might not be the really most recent version and that one should check the english one for this. Dunno if that would be fine for everyone ?!

[martinsik]

@JWO719 3.1. Maybe when translating class methods they all could go to a single file and be referenced eg. like /docs_app/i18n/de/observable#subscribe so there'll be just one file with translations (it should work with convention like you mentioned as well)

How is language switching going to be implemented in doc-app?

I was thinking about the same thing as Pete that it'll be hard to maintain existing translations with their english source. I think a lot of changes to documentation are just small adjustments that are hard to spot and even worst it requires good understanding of RxJS to be able to tell how it's different.
So if there could be a CLI tool that would check what translations files you changed and then dumped their commit ids together with commit ids for their english counterparts and then later when the english source changes you could just run it again and it would dump files and their diffs that have changed since their translation was last updated.

[luillyfe]

@JWO719 @martinsik @petebacondarwin not sure if I understood well, which approached is the suggested to start with?

[petebacondarwin]

I don't know what the best approach to translation is yet, which is one of the reasons why we have not implemented it for angular.io yet.

[niklas-wortmann]

I personally would start with translating the static content (point 1 from above). I think this is much less effort and we can get some feedback on two things:

1. Do we get active support with the translations
2. Do developers prefer their native language (propably yes :D)

For the static content we are already using the folder structure for the navigation if we now add a folder 'en' for the english documents and besides that a folder e.g. 'de' for the german translations, most of the things should more or less work. Their might be some troubles here and there to load the correct file but I'm quite optimistic that this could be done relatively easy. Afterwards we can better forsee the impact and needed effort for translating the api docs.
I'm very happy to support everyone who is willing to spend some time and dig into this.

[benlesh]

I don't think we have the bandwidth for this right now. Closing this just to clean things up. But we are indeed aware that there is _some_ desire to translate the documentation. Hopefully Google Translate will suffice in the interim.