From b.rowlingson at lancaster.ac.uk  Mon Aug  5 00:22:23 2013
From: b.rowlingson at lancaster.ac.uk (Barry Rowlingson)
Date: Sun, 4 Aug 2013 23:22:23 +0100
Subject: [Rd] [R] Internalization of help pages
In-Reply-To: <84705d8af5c14f2a886fe96afb4bcd56@EX-0-HT0.lancs.local>
References: <cagku+8b57gjwpcxbdr9-sgzd2w8ukhn=u40vgzwtjacuqb7f=w@mail.gmail.com>
	<51fd9e3c.4080202@bitwrit.com.au>
	<cack-te30koykr6qjcyaqxrjg3humnrraxjelwukercxgoxun3w@mail.gmail.com>
	<cagku+8cmodkzgkd1dvxa2qmwjvxkvjvfh7n9pzeptneykau3ww@mail.gmail.com>
	<51FDA03A.5020304@bitwrit.com.au>
	<84705d8af5c14f2a886fe96afb4bcd56@EX-0-HT0.lancs.local>
Message-ID: <CANVKczMX1g0bLwRbQ-F_-mX9Sk0HbvxWjfxXQLc7F--sVZU_wQ@mail.gmail.com>

[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



[Rd] [R] Internalization of help pages
Barry Rowlingson