[Rd] [R] Internalization of help pages

[Barry Rowlingson]

[I've tried to move this back to R-devel, which I think is what Brian
Ripley tried and nobody followed...]

On Sun, Aug 4, 2013 at 4:15 PM, John Kane <jrkrideau at inbox.com> wrote:
> I tried it in French and there a few hiccups but it's not too bad.
>
> Personally I'd like to see the help tranlated into English too.l
>
> John Kane
> Kingston ON Canada

 The problems of getting translations for help pages are many-fold:

1. Giving translators access to current .Rd files, which is tricky
when people are developing with roxygen2.
2. Finding translators to do the work. There are a lot of tools for
helping translate message files, but whole .Rd docs might be too much
for the casual translator.
3. Having a standard way to display help in language X if it exists,
considering the complexity of R's help (plain text, web, PDF
versions). Put it all in help/XX and html/XX and doc/XX for XX in
languages?
4. As (3) but with vignettes. Wouldn't vignette("foo",language="fr")
be nice if "foo" was available in French? Or vignette(language="de")
to get all German vignettes?
5. Language bloat. Best solved by making language documentation 'add
on' packs. Easier for a package developer to do for one package, hard
for core R with several packages and core documentation.
6. How do you integrate that with CRAN?
7. Does CRAN have to build all the built languages documentation from
the language .Rd files? A standard repository structure on github and
some github_ wrapper functions might help kick this off since there
wouldn't be a need to bother the busy CRAN people with things.

Of all of that I reckon foreign-language vignette support might be the
easiest to implement. It would seem to require a way for an author to
specify the language of a vignette, a standard place for languaged
vignettes (source and built), and a mod to the vignette function to
look in those places.

The comparable translation project I know of is the translation of
documents for the OSGeo Live DVD - this consists of translations of
short project introductions and walkthroughs (with screenshots) for
about 50 pieces of software, which is probably of the order of
difficulty of translating an R package with about 100 well-documented
functions. It works well but it does have a lot of commitment from
everyone every six months at the release points.

However, getting all the R documentation translated is probably easier
than getting everyone to speak english - we started trying to do that
in the 18th century and look how that turned out...

Barry