Discussion of Documentation Localization of SkyWalking 9.x

[Superskyyy]

This discussion is based on my trials on different localization platforms and now it's time to share the core steps for making it work for us. Ref: apache/skywalking-website#522

The main problem of maintaining translation is that project documentation constantly gets updates and it's painful to diff and sync, so we need a professional tool for it.

After trying a bunch, I found https://www.transifex.com/ to be the go-to platform for hosting an open-source crowd-sourcing project that we can collaborate on producing localizations, it's widely used by other big OSS projects and they have a free plan for OSS. It will automatically take care of diff updated docs and provide memorization of glossaries.

The flow is quite simple, 1. uploading* .md files and setup a sync mechanism. 2. do the translation work. 3. pull the translated .md back.

The pending task to do before execution:

1. Our markdown is sometimes malformed, especially with soft line wraps will confuse the parser, a GitHub action/automation is needed to first prettify it. Then push to Transifex using their API.
2. If we continue to use the SkyAPM repo, we can set a cron job there to pull translated files every now and then.

Two possible places to run the action:

1. trigger-based, hosted in each repo whenever there's a PR update to any .md, transform and update that particular file to Transifex.
2. cron-based, gather project docs from time to time in website/translation repo and update to Transifex. This is not really desirable since we don't want to push all .mds every x hours.

[wu-sheng]

https://www.transifex.com/pricing/ This tool seems a commercial one, I am not sure whether it would be accepted in the ASF repo, and we also need sponsors, the price starts 70USD/Mo.

And, the reason I mentioned it in some OSS programs, is that it is hard to ask ppl following translation work continues in months/years. Translating one version's doc may be possible, but to keep going to follow our main repo iteration is hard unless it is a part of the work. But AFAIK, there is no one treating this as a daily job.

[wu-sheng]

Say we produce an initial fully translated version of 9.x (many could migrate from previous doc translation), even if without any maintenance the translated version will only slowly degrade in quality until every sentence in the initial one is gone.

Do we have volunteers to do this? For 9.2 or the v9-dev?

And, does that tool require setup in the main repo? I don't want any surprise to the ASF INFRA.

[Superskyyy]

Say we produce an initial fully translated version of 9.x (many could migrate from previous doc translation), even if without any maintenance the translated version will only slowly degrade in quality until every sentence in the initial one is gone.

Do we have volunteers to do this? For 9.2 or the v9-dev?

And, does that tool require setup in the main repo? I don't want any surprise to the ASF INFRA.

I can complete the initial full translation work, relying on a neural translation tool will help me to produce an acceptable version very quickly then improve along the way. I will begin this weekend.

I think not really need anything to be installed into the repo, no permission is needed. After the initial translation, I will write an action to push docs to an API endpoint when they are updated in PR. Other logic will not happen in main repo.

[wu-sheng]

Do you need some setup for that repo? I could assign you as admin if needed.

[Superskyyy]

Do you need some setup for that repo? I could assign you as admin if needed.

I'll need to store some API keys to access the Transifex platform, I suppose I will need to add them through repository secrets?

[wu-sheng]

I have assigned you as admin for that repo, you should be good go.