Hi Jark, Thanks so much for evaluating Docusaurus and Crowdin and writing up this report! It seems that staying with the current approach and avoiding the effort of porting the documentation is the best solution for now.
We might want to reconsider Docusaurus if we want to restructure the documentation completely at some point. Thanks, Fabian Am Do., 14. Feb. 2019 um 16:41 Uhr schrieb Jark Wu <imj...@gmail.com>: > Hi all, > > Qianjing Xu and I have been exploring Docusaurus and crowdin in recent days > to see how can Flink fit into them to support multi-language. > > Here is the summary from our side: > (we didn't learn deeply, so we may miss something or misunderstand. Please > correct us if we are wrong) > > # What is Docusaurus and crowdin ? > Docusaurus [1] is a documentation framework which supports document > versioning and localization (via crowdin). IMO, Docusaurus is something > similar to Jekyll. > Crowdin[2] is a localization management platform. Users can upload contents > (e.g. markdown source files) to crowdin and translate, collaborate, manage > process on crowdin. > The English contents is kept in the original repository, and the multiple > language translated contents is kept in crowdin. We need to download the > translated contents from crowdin and build them into localization website. > Apache Pulsar is using them for website and documentation as @Sijie > mentioned above. > Here is the Pulsar project on crowdin [3]. > And here is a test project for Flink I created [4]. > > # How can Flink fit into them? > I'm afraid that Flink is hard to fit into Docusaurus unless we rework our > website/docs from Jekyll to Docusaurus. > > How about Jekyll + Crowdin? > We need a build job to make it work. The build job is triggered when a > commit merged into master. > The build job does the following things: > 1) upload the lastest contents (English markdown source files) from git to > crowdin. > - If the source content is changed, the corresponding translation will > lose and need re-translation. > 2) download the translated contents > 3) build website and publish > > But it seems that Crowdin doesn't fit well with Jekyll. > Crowdin will break contents into multiple lines to translate according his > syntax. This results to the layout broken. > For example, the translated metric page is not rendered as expect: > this is the original `metric.md`: > > https://user-images.githubusercontent.com/5378924/52795366-9a22f080-30ac-11e9-9cfd-4de82041aa77.png > this is the file downloaded from crowdin: > > https://user-images.githubusercontent.com/5378924/52795379-9f803b00-30ac-11e9-9700-0a4077b5882d.png > this is the page after rendered: > > https://user-images.githubusercontent.com/5378924/52795389-a5761c00-30ac-11e9-9821-35c705a8d65b.png > > So it seems that currently crowdin works less well when the markdown > contains HTML and Liquid codes. > > # Conclusion (Docusaurus/crowdin or previous proposal) > I'm leaning more towards the previous proposal [5]. Not only because > crowdin works less well for Flink currently. > But also it introduces much new things and tools to learn for contributors. > Furthermore the previous proposed translate process works good when we > experiment it in Flink website. > > What do you think? > > Regards, > Jark > > [1]: https://docusaurus.io/en/ > [2]: https://crowdin.com/ > [3]: https://crowdin.com/project/apache-pulsar/zh-CN# > [4]: https://crowdin.com/project/flink-test/zh-CN# > [5]: > > https://docs.google.com/document/d/1R1-uDq-KawLB8afQYrczfcoQHjjIhq6tvUksxrfhBl0/edit# > > > On Tue, 12 Feb 2019 at 23:48, Xingcan Cui <xingc...@gmail.com> wrote: > > > Hi, > > > > I agree with the proposal, Gordon and Jark, and I think it's a good > > solution for major doc changes. We also created separated JIRAs for > English > > documentation in the past. > > > > For minor doc changes, I think it’s better to encourage Chinese-speaking > > contributors to participate in the reviewing process and help translate > the > > few lines in sync. > > > > Best, > > Xingcan > > > > > On Feb 12, 2019, at 7:04 AM, Jark Wu <imj...@gmail.com> wrote: > > > > > > Hi @Sijie, > > > > > > Thank you for the valuable information. I will explore Docusaurus and > > > feedback here. > > > > > > Best, > > > Jark > > > > > > On Tue, 12 Feb 2019 at 18:18, Fabian Hueske <fhue...@gmail.com> wrote: > > > > > >> Hi everyone, > > >> > > >> +1 to what Gordon and Jark proposed. > > >> We should make use of the review bot to ensure that new features are > > >> documented at least in English. > > >> If the Chinese docs are not updated, a Jira issue must be created. > > >> > > >> @Sijie, thank for the pointer to Docusaurus! IMO, this looks very > > >> interesting and should be worth exploring. > > >> > > >> Thanks, Fabian > > >> > > >> > > >> > > >> Am Di., 12. Feb. 2019 um 09:06 Uhr schrieb Sijie Guo < > si...@apache.org > > >: > > >> > > >>> Hi, > > >>> > > >>> Sorry for interrupting the thread. But this topic sounds interesting > to > > >> me. > > >>> It might be worth for you guys checking out docusaurus > > >>> https://docusaurus.io/docs/en/translation . Docusaurus is a > > >> documentation > > >>> framework open sourced by Facebook. It has handled versioning and > > >>> localization (via crowdin) pretty good. Apache Pulsar is using it for > > its > > >>> website and documentation. > > >>> > > >>> - Sijie > > >>> > > >>> On Mon, Jan 28, 2019 at 7:59 PM Jark Wu <imj...@gmail.com> wrote: > > >>> > > >>>> Hi all, > > >>>> > > >>>> In the past year, the Chinese community is working on building a > > >> Chinese > > >>>> translated Flink website (http://flink.apache.org) and documents ( > > >>>> http://ci.apache.org/projects/flink/flink-docs-master/) in order to > > >> help > > >>>> Chinese speaking users. This is http://flink-china.org and it has > > >>> received > > >>>> a lot of praise since online. > > >>>> > > >>>> In order to follow the Apache Way and grow Apache Flink community, > we > > >>> want > > >>>> to contribute it to Apache Flink. It contains two parts to > contribute: > > >>>> (1) the Chinese translated version of the Flink website > > >>>> (2) the Chinese translated version of the Flink documentation. > > >>>> > > >>>> But there are some questions are up to discuss: > > >>>> > > >>>> ## The Address of the translated version > > >>>> > > >>>> I think we can add a Chinese channel on official flink website, such > > >> as " > > >>>> https://flink.apache.org/cn/";, which is similar as " > > >>>> http://kylin.apache.org/cn/";. And use " > > >>>> https://ci.apache.org/projects/flink/flink-docs-zh-master/"; to put > > the > > >>>> Chinese translated docs. > > >>>> > > >>>> ## Add a link to the translated version > > >>>> > > >>>> It would be great if we can add links to each other in both Chinese > > >>> version > > >>>> and English version. For example, we can add a link to the > translated > > >>>> website on the sidebar of the Flink website. We can also add a > > dropdown > > >>>> button for the Chinese document version under the "Pick Docs > Version" > > >> in > > >>>> Flink document. > > >>>> > > >>>> ## How to contribute the translation in a long term > > >>>> > > >>>> This is a more important problem. Because translation is a huge and > > >>>> long-term work. We need a healthy mechanism to ensure the > > >> sustainability > > >>> of > > >>>> contributions and the quality of translations. > > >>>> > > >>>> I would suggest to put the Chinese version document in flink repo > > (such > > >>> as > > >>>> "doc-zh" folder) and update with the master. Once we modify the > > English > > >>>> doc, we have to update the Chinese doc together, or create a JIRA > > >>> (contains > > >>>> git commit id refer to the English modification) to do that. This > will > > >>>> increase some workload when we update the doc. But this will keep > the > > >>>> Chinese doc up to date. We can attract more Chinese contributors to > > >> help > > >>>> build the doc. And the modification is small enough and easy to > > review. > > >>>> > > >>>> Maybe there is a better solution and we can also learn how the other > > >>>> projects do it. > > >>>> > > >>>> Any feedbacks are welcome! > > >>>> > > >>>> Best, > > >>>> Jark Wu > > >>>> > > >>> > > >> > > > > >
