[llvm-dev] llvm/clang documentation i18n ?

[Reid Kleckner via llvm-dev]

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>