Localization support for user/developer documents

[dynamis]

Currently profiler itself support l10n but user/developer docs are written only in English ad markdown and don't support any l10n (translation).

If you host documents on project specific site profiler.firefox.com instead of MDN (see also #1199), the site should support l10n.

You may use docusaurus or any other framework with i18n support, or you should host user/developer documents on MDN since most document translation contributors are working on MDN.

┆Issue is synchronized with this Jira Task

[julienw]

We use docsify, here is how they handle it: https://github.com/docsifyjs/docsify/blob/79a66199807f4b824e1eb868a551a1ca28d63b64/docs/index.html#L75-L82

In short, with links to other websites, which could be other repositories or npm packages on this case.

Happy to hear other thoughts.

[mstange]

I don't like docsify's URLs (fragment for the page, query string for the anchor) or its default stylesheet very much. I think it would be nice to migrate away from it. I also think it would be good to host documentation on another host (e.g. docs.profiler.firefox.com) so that we can insta-deploy it instead of waiting for main profiler deploys. And having the documentation separate would mean that the profiler "build output" would be smaller because it would no longer include the documentation with its large images, making it easier to bundle the build output with command line profilers or converters which don't want to depend on an internet connection.

[julienw]

I want to point out a few things:

1. We (Mozilla) don't host app docs in MDN anymore, this is all in firefox-source-docs now.
2. firefox-source-docs isn't localized. That's why we haven't really thought about that so far.
3. The most difficult thing with localization isn't the initial translation, but how do we ensure this stays uptodate. Mozilla's answer to that for apps is pontoon, but I don't know what our answer is for content. It could be good to look at what we're doing on websites such as mozilla.org. @flodolo do you know?

[julienw]

Answering Markus comment now:

I don't like docsify's URLs (fragment for the page, query string for the anchor) or its default stylesheet very much.

If the stylesheet isn't good, there's an easier solution than migrating to another solution... Change the stylesheet :-)

I think it would be nice to migrate away from it. I also think it would be good to host documentation on another host (e.g. docs.profiler.firefox.com) so that we can insta-deploy it instead of waiting for main profiler deploys.

This would be a nice result indeed.

And having the documentation separate would mean that the profiler "build output" would be smaller because it would no longer include the documentation with its large images, making it easier to bundle the build output with command line profilers or converters which don't want to depend on an internet connection.

I'm not sure to follow. In our current build setup the documentation is essentially separate already, the files are merely just copied. This is actually one nice thing of docsify: all the markdown building work is client side. I believe that what you really want here is that we use an absolute URL in our documentation links instead of a relative one, so that you can use the result of the build without the docs.

To sum up, I'm not opposed. But this is some work to do for a small user value IMO...

[flodolo]

Pontoon only supports strings, not free text content. mozilla.org is localized by splitting up the original web page in individual sentences (Fluent strings), and translating them one by one. That's not a system that I would use for documentation, because it doesn't scale.

SUMO, for example, uses a completely custom engine to maintain this type of content translation. MDN simply gave up on that, and now uses markdown for a very limited number of locales, and I have no idea how easy it is to track content and status (probably very hard).

I don't think localizing this is a good use of limited sources, and it would require some custom platform to keep content safely up to date. Even tools like mdbook don't have multilingual support yet.

For sure, I wouldn't force locales who decided to translate the Profile itself to also support translation of documentation.