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