Share some experience for the current translation(and review) process from my side. for documentation review, we can pull the patch locally and set up a local server[1][2], after that, we can reference the rendered documentation in `localhost:4000`
[1] https://flink.apache.org/contributing/contribute-documentation.html#update-or-extend-the-documentation [2] https://flink.apache.org/contributing/improve-website.html#update-or-extend-the-documentation Best, Congxian Yun Tang <myas...@live.com> 于2020年6月9日周二 下午10:34写道： > Hi > > I think supporting website with another language should be okay. However, > I'm afraid Flink community lacks of resources > to maintain technical documentations of another languages currently. > > From my experiences of translating documentation to Chinese since the past > year, I found > Chinese documentation is easy to be out-of-date and containing broken > links. Some developers > might only update English version and forget to update the related Chinese > version. > > Since Jark talked about re-investigating tools for translating, I just > want to share some painful experiences > when translating documentations. > First of all, I think code review should be totally different from doc > review. Github lacks such kind of power > to make the markdown review more readable, we often need to read a long > line without wrapping and give advice for > just some of the characters. > Secondly, user who wants to contributes cannot leverage any given powerful > tool. > > I think Crodwin might be a good choice. > > 1. Many popular projects already use this: node.js [1], gitlab [2], > Minecraft [3]. > 2. This tool is free for open-source project [4] > > [1] https://crowdin.com/project/nodejs-website > [2] https://crowdin.com/project/gitlab-ee > [3] https://crowdin.com/project/minecraft > [4] https://crowdin.com/page/open-source-project-setup-request > > Best > Yun Tang > > ________________________________ > From: Marta Paes Moreira <ma...@ververica.com> > Sent: Tuesday, June 9, 2020 22:13 > To: dev <dev@flink.apache.org> > Subject: Re: [DISCUSS] Add Japanese translation of the flink.apache.org > website > > I had a second look at the PR and maybe it'd be important to clarify the > scope. > > It seems to only target the website and, if that's the case, then > synchronization might be less of an issue as the core of the website is > pretty static. I'm not sure how useful it is to have a translated website > without any other kind of support (e.g. mailing list, documentation) in the > same language, but the contributor might be able to shed some light on > this. > > Just wanted to amend my original reply as it was pretty blindsided by the > previous comments. It'd be worth understanding the end goal of the > contribution first. > > Thanks, > > Marta > > On Tue, Jun 9, 2020 at 2:22 PM Congxian Qiu <qcx978132...@gmail.com> > wrote: > > > Hi > > > > Thanks for bringing this up, Robert. > > > > I agree we may need to investigate better translation/synchronization > tools > > again. > > > > I'll share some experience when translating the documentation or > reviewing > > the translation. > > 1. Translate documentation using the current procedure needs a lot of > > resources to keep the translated version fresh, I'm glad that we have so > > many contributors who want to translate the documentation to Chinese. > > 2. The documentation may out of sync between the English version and the > > translated version, this needs the reviewer to know about Flink and the > > English version doc very well(especially when the documentation has been > > restructured) > > > > Best, > > Congxian > > > > > > Jark Wu <imj...@gmail.com> 于2020年6月9日周二 下午6:02写道： > > > > > I agree with Dawid and others' opinions. > > > > > > We may not have enough resources to maintain more languages. > > > Maybe it's time to investigate better translation/synchronization tools > > > again. > > > > > > I want to share some background about the current translation process. > In > > > the initial proposal of Chinese translation FLIP-35 [1], > > > we have considered Docusaurus/Crowdin as the localization tool, but it > > > seems that Crowdin doesn't fit well with Jekyll (Liquid codes). > > > But it's been a year and a half, maybe it's time to re-investigate them > > or > > > other tools. > > > > > > Here is the list of how other ASF projects are dealing translation of > > what > > > I know: > > > - Apache Pulsar uses Crowdin: > > https://github.com/apache/pulsar-translation > > > - Apache Kylin: the similar way of Flink: > > > https://github.com/apache/kylin/tree/document/website > > > - Apache RocketMQ: a separate repository, synchronize manually and > > > periodically: https://github.com/apache/rocketmq/tree/master/docs/cn > > > > > > Here is the list of localization tool of what I know: > > > - Docusaurus: https://docusaurus.io/ > > > - Crowdin: https://crowdin.com/ > > > - GitLocalize: https://gitlocalize.com/ > > > > > > Best, > > > Jark > > > > > > On Tue, 9 Jun 2020 at 16:24, Marta Paes Moreira <ma...@ververica.com> > > > wrote: > > > > > > > Thanks for bringing this PR to our attention, Robert! > > > > > > > > Like Dawid and Xintong, I'm concerned that adding a new language will > > > make > > > > it unbearable to ensure docs synchronization. Best-effort maintenance > > of > > > > non-english docs may also result in a bad documentation experience > for > > > > users, and this is something that we should be especially careful > about > > > in > > > > locations where Flink adoption might still be in an early phase, IMO. > > At > > > > the same time, I understand that having a japanese translation would > > > > probably be very helpful for Japanese-speaking users and help with > > Flink > > > > adoption in Japan. > > > > > > > > I see this happening for other up-and-coming locations (e.g. > > > > Spanish-speaking countries) in the future, so in order to be able to > > > accept > > > > these contributions I'm also of the opinion that we first need an > > > efficient > > > > synchronization tool. Maybe it would be worth investigating how other > > ASF > > > > projects are dealing with this. > > > > > > > > Marta > > > > > > > > On Mon, Jun 8, 2020 at 11:46 AM Xintong Song <tonysong...@gmail.com> > > > > wrote: > > > > > > > > > I think Dawid has a good point. With or without another new > language, > > > > > I'm +1 for trying to have a better tooling/process for > synchronizing > > > doc > > > > > changes. > > > > > > > > > > Currently, it is not only hard for people who want to modify the > > > English > > > > > docs, but also for people who try to update the translated copies > > > > > accordingly. I'm currently working on updating the Chinese > > translations > > > > for > > > > > the memory configuration documents, and I found it very hard to > > > identify > > > > > the parts that need updates. The English docs are reorganized, > > contents > > > > are > > > > > moved across pages, and also small pieces of details are modified. > It > > > is > > > > > not always possible for people who work on the English docs to > locate > > > the > > > > > right place in the translations where the updated contents should > be > > > > > pasted. > > > > > > > > > > My two cents on the potential approach. We might label the > > translation > > > > with > > > > > the commit id of the original doc where they are in > synchronization, > > > and > > > > > automatically display a warning on the translation if an > out-of-sync > > is > > > > > detected. > > > > > > > > > > Thank you~ > > > > > > > > > > Xintong Song > > > > > > > > > > > > > > > > > > > > On Mon, Jun 8, 2020 at 4:30 PM Dawid Wysakowicz < > > > dwysakow...@apache.org> > > > > > wrote: > > > > > > > > > > > I don't have a well defined opinion on adding new language. > > However, > > > > one > > > > > > thing that I'd like to bring up to the attention on that occasion > > is > > > it > > > > > > is already quite cumbersome to update two versions of the docs. > > > > > > Especially when we add new sections or change smaller parts of an > > > > > > existing document. Right now if I add three sections in an > English > > > > > > version I have three additional places in the Chinese documents > > > where I > > > > > > need to paste that. With additional language it doubles, making > it > > 6 > > > > > > places where I have to manually paste the added parts. > > > > > > > > > > > > I'd be way more welcoming for adding a new language if we had a > > > better > > > > > > tooling/process for synchronizing changes across different > > languages. > > > > Or > > > > > > if we agree the translations are best effort documents and we do > > not > > > > > > update them when changing the English documents. > > > > > > > > > > > > Best, > > > > > > > > > > > > Dawid > > > > > > > > > > > > On 08/06/2020 09:44, Robert Metzger wrote: > > > > > > > Hi all, > > > > > > > > > > > > > > we've received a pull request on flink-web.git for adding a > > > Japanese > > > > > > > translation of the Flink website: > > > > > > > https://github.com/apache/flink-web/pull/346 > > > > > > > > > > > > > > Before we accept this PR, I believe we should have a discussion > > > about > > > > > it. > > > > > > > > > > > > > > *Relevance*: Looking at Google analytics, our users are coming > > from > > > > > China > > > > > > > (1.), US (2.), India (3.), Germany (4.), Japan (5.). > > > > > > > I'd say that is high enough to consider a Japanese translation. > > > > > > > > > > > > > > *Reviewing*: I'm not aware of any committer who speaks > Japanese. > > > How > > > > > > would > > > > > > > we review this? > > > > > > > The contributor is offering to open follow-up pull requests, > > which > > > I > > > > > > > believe is fine to bootstrap. Ideally we'll be able to attract > > more > > > > > > > contributors over time. > > > > > > > > > > > > > > In my opinion, if we find one or two reviewers, I would give > > this a > > > > > try. > > > > > > > > > > > > > > What do you think? > > > > > > > > > > > > > > Best, > > > > > > > Robert > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >
