Hi James, Yes, documents changes over the time. And keeping them up-to-date would takes a lot of efforts. I tried years ago (2013~2015) with clang v3.4 , and finally I gave up. It's too much for one person to complete. The reason I come up again with this idea is that I saw people still referencing the partial complete Chinese docs and sharing it among others. And there's other people doing the same thing (translating, sharing, revise). So what if we gather all the effort together? maybe we would succeed with a number of helping hand.Even if we failed, then we would learn some lessons and leave something for others to try. The only bad things is another dead doc repo? So how about: 1. just give up the idea about up-to-date, stick to one version a time. e.g.: we first translate version 7.0, and when we done, it's version 9.0. then we skip version 8.0. start from 9.0, and so on. each document mark with specific version number. 2. at the very beginning, we separate the i18n documents from the mono-repo, given a more relaxed commit standard and see what happens? FYI: 1. A lot of people seeking for Chinese documents is in academy (teachers and students). So this project would have great influence on them. And they are more likely to contribute to llvm/clang project in return. 2. This would have even further impact. like helping tech writers and authors. Regards, Max On Wed, Feb 26, 2020 at 5:08 PM James Henderson <jh7370.2008 at my.bristol.ac.uk> wrote:> > Hi Max, > > Whilst I wholeheartedly support the concept of translating the docs into other languages, the problem with it is that they are likely to rot very quickly as changes are made to the canonical English versions. How would you propose these be kept up-to-date? > > James > > On Wed, 26 Feb 2020 at 00:49, yun xinyi via llvm-dev <llvm-dev at lists.llvm.org> wrote: >> >> Hi everyone, >> >> I have translated part of the llvm/clang documentation (from English to Chinese). >> I wonder if it's possible to merge them into llvm-project/doc ? >> Or place a link or short description on llvm.org to direct people to the same repo to save duplicate efforts and make it more updated and complete? >> >> Regards, >> Max >> >> _______________________________________________ >> LLVM Developers mailing list >> llvm-dev at lists.llvm.org >> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
Reid Kleckner via llvm-dev
2020-Feb-26 18:58 UTC
[llvm-dev] llvm/clang documentation i18n ?
I think there is a lot of value in translating the most commonly used docs to Chinese. However, my first reaction is that we should put more effort into writing good docs before others take the time to translate them. :) But, don't let that stop you. What is your opinion on the approach taken by sphinx-intl? http://www.sphinx-doc.org/en/master/usage/advanced/intl.html Do you think it would be better to have llvm/docs/zh with a complete fork of the translated documentation in markdown / rst, or better to use gettext and related tools to slice the English text into paragraphs which can be translated one by one with less duplication of the structure? I think your idea of a separate git repo might be best. I think you will want to enable as many users as possible to contribute translations without the overhead of code review or getting llvm-project push access. LLVM could probably pull this repo as part of the script that generates the official documentation and incorporate it that way. On Wed, Feb 26, 2020 at 9:55 AM yun xinyi via llvm-dev < llvm-dev at lists.llvm.org> wrote:> Hi James, > > Yes, documents changes over the time. > And keeping them up-to-date would takes a lot of efforts. > > I tried years ago (2013~2015) with clang v3.4 , and finally I gave up. > It's too much for one person to complete. > The reason I come up again with this idea is that I saw people still > referencing the partial complete Chinese docs and sharing it among > others. > And there's other people doing the same thing (translating, sharing, > revise). > So what if we gather all the effort together? maybe we would succeed > with a number of helping hand.Even if we failed, then we would learn > some lessons and leave something for others to try. The only bad > things is another dead doc repo? > > So how about: > 1. just give up the idea about up-to-date, stick to one version a > time. e.g.: we first translate version 7.0, and when we done, it's > version 9.0. then we skip version 8.0. start from 9.0, and so on. each > document mark with specific version number. > 2. at the very beginning, we separate the i18n documents from the > mono-repo, given a more relaxed commit standard and see what happens? > > FYI: > 1. A lot of people seeking for Chinese documents is in academy > (teachers and students). So this project would have great influence on > them. And they are more likely to contribute to llvm/clang project in > return. > 2. This would have even further impact. like helping tech writers and > authors. > > Regards, > Max > > > On Wed, Feb 26, 2020 at 5:08 PM James Henderson > <jh7370.2008 at my.bristol.ac.uk> wrote: > > > > Hi Max, > > > > Whilst I wholeheartedly support the concept of translating the docs into > other languages, the problem with it is that they are likely to rot very > quickly as changes are made to the canonical English versions. How would > you propose these be kept up-to-date? > > > > James > > > > On Wed, 26 Feb 2020 at 00:49, yun xinyi via llvm-dev < > llvm-dev at lists.llvm.org> wrote: > >> > >> Hi everyone, > >> > >> I have translated part of the llvm/clang documentation (from English to > Chinese). > >> I wonder if it's possible to merge them into llvm-project/doc ? > >> Or place a link or short description on llvm.org to direct people to > the same repo to save duplicate efforts and make it more updated and > complete? > >> > >> Regards, > >> Max > >> > >> _______________________________________________ > >> LLVM Developers mailing list > >> llvm-dev at lists.llvm.org > >> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev > _______________________________________________ > LLVM Developers mailing list > llvm-dev at lists.llvm.org > https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev >-------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20200226/fb27342f/attachment.html>
1. sphinx-intl seems the best option. 2. gettext and related tools would be sufficient (maybe some web-based translation service later.) 3. A separate repo would accelerate the process without too much review overhead. which can also be a git submodule of llvm-project 4. translation would be sub folder of the document folder with language code as its name On Thu, Feb 27, 2020 at 2:58 AM Reid Kleckner <rnk at google.com> wrote:> > I think there is a lot of value in translating the most commonly used docs to Chinese. > > However, my first reaction is that we should put more effort into writing good docs before others take the time to translate them. :) But, don't let that stop you. > > What is your opinion on the approach taken by sphinx-intl? > http://www.sphinx-doc.org/en/master/usage/advanced/intl.html > > Do you think it would be better to have llvm/docs/zh with a complete fork of the translated documentation in markdown / rst, or better to use gettext and related tools to slice the English text into paragraphs which can be translated one by one with less duplication of the structure? > > I think your idea of a separate git repo might be best. I think you will want to enable as many users as possible to contribute translations without the overhead of code review or getting llvm-project push access. LLVM could probably pull this repo as part of the script that generates the official documentation and incorporate it that way. > > On Wed, Feb 26, 2020 at 9:55 AM yun xinyi via llvm-dev <llvm-dev at lists.llvm.org> wrote: >> >> Hi James, >> >> Yes, documents changes over the time. >> And keeping them up-to-date would takes a lot of efforts. >> >> I tried years ago (2013~2015) with clang v3.4 , and finally I gave up. >> It's too much for one person to complete. >> The reason I come up again with this idea is that I saw people still >> referencing the partial complete Chinese docs and sharing it among >> others. >> And there's other people doing the same thing (translating, sharing, revise). >> So what if we gather all the effort together? maybe we would succeed >> with a number of helping hand.Even if we failed, then we would learn >> some lessons and leave something for others to try. The only bad >> things is another dead doc repo? >> >> So how about: >> 1. just give up the idea about up-to-date, stick to one version a >> time. e.g.: we first translate version 7.0, and when we done, it's >> version 9.0. then we skip version 8.0. start from 9.0, and so on. each >> document mark with specific version number. >> 2. at the very beginning, we separate the i18n documents from the >> mono-repo, given a more relaxed commit standard and see what happens? >> >> FYI: >> 1. A lot of people seeking for Chinese documents is in academy >> (teachers and students). So this project would have great influence on >> them. And they are more likely to contribute to llvm/clang project in >> return. >> 2. This would have even further impact. like helping tech writers and authors. >> >> Regards, >> Max >> >> >> On Wed, Feb 26, 2020 at 5:08 PM James Henderson >> <jh7370.2008 at my.bristol.ac.uk> wrote: >> > >> > Hi Max, >> > >> > Whilst I wholeheartedly support the concept of translating the docs into other languages, the problem with it is that they are likely to rot very quickly as changes are made to the canonical English versions. How would you propose these be kept up-to-date? >> > >> > James >> > >> > On Wed, 26 Feb 2020 at 00:49, yun xinyi via llvm-dev <llvm-dev at lists.llvm.org> wrote: >> >> >> >> Hi everyone, >> >> >> >> I have translated part of the llvm/clang documentation (from English to Chinese). >> >> I wonder if it's possible to merge them into llvm-project/doc ? >> >> Or place a link or short description on llvm.org to direct people to the same repo to save duplicate efforts and make it more updated and complete? >> >> >> >> Regards, >> >> Max >> >> >> >> _______________________________________________ >> >> LLVM Developers mailing list >> >> llvm-dev at lists.llvm.org >> >> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev >> _______________________________________________ >> LLVM Developers mailing list >> llvm-dev at lists.llvm.org >> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev