Documentation Translation

In the thread about IDE translation, Scott Carver wrote:

> We currently have no way of providing localized versions of documentation
- that's a big-ish engineering task in itself... without that, there's
really no use in translating documentation in the first place.

I agree, and I'd like to start a discussion about that. Internationalizing
SuperCollider is, I think, a topic where we all agree Something Should Be
Done. :)

Note that in this email I'm _only_ discussing technical issues, not the
questions of who will translate, what will their experience be like, how
will we organize that, and so on. It will be of course important to
consider that as well.

From a technical standpoint, there are at least five different categories
of strings that ought to be internationalized:

1. SCDoc documentation
2. Non-SCDoc documentation (readmes, installation guides, etc)
3. Qt-translatable strings (mainly, the IDE)
4. Messages that come from C++ code that isn't Qt-translatable - sclang,
scsynth, supernova
5. Messages that come from within the SuperCollider class library

The "most important" things to translate (core documentation, installation
guides, common error messages, UI elements) come from all 5 categories.
Here's how well each structure currently supports internationalization:

1. None
2. Nearly perfect (we just provide a new directory structure and add _es,
_po, etc. to each translated file, or something similar)
3. Perfect
4. None
5. None

By my estimation, the amount of effort required to add support for (1) and
(4) is about the same; for (4), I think a possible solution is to use the
GNU gettext <https://www.gnu.org/software/gettext/manual/gettext.html>
suite. For (5), probably the most practical solution is to simply call down
to gettext and keep all our translations for the class library + sclang
strings in the same place.

For (1), I have some thoughts:

I think it would be a reasonable design decision to allow users to switch
between languages within the SCDoc browser. I was imagining a dropdown menu
on the top bar that simply lets you select language.

An overview of what I understand to be the standard usage is:
- SCDoc is set to some language Lang
- Each time SCDoc navigates to a new page, it searches for the Lang version
of that page. If it can't be found, it defaults to the English version.

Some of the modifications necessary to make this happen are:
- Have some way of indicating language to SCDoc. I think the dead simple
way to do this would be to just place everything we have right now into
`HelpSource/en/`, and create new directories for each language for which we
have translations.
- Update the way SCDoc searches for and navigates help files to fit this
new scheme.

Indexing the help files is slow. Maybe for each language we only want to
index the files in that language, plus the English files? Then, re-indexing
would only need to happen if the desired doc language is changed, which
should be infrequent.

I also agree with what Scott wrote here:

> It might be useful to have some of SC's spanish language users build a
rough prioritized list of improvements to SC's localization. Translating
the IDE UI seems straightforwardly useful - but spanish language
documentation is a *very* large and open-ended task. Breaking this into
smaller tasks would make it much easier for people to contribute, and make
sure their contributions are hitting the most important things first. For
example, is it better to spend time translating guides, or documentation of
important core classes? Is it important to translate all the help
navigation terminology to spanish (e.g. "Search", "Browse", "Classes"), or
better to simply spend that time on class docs themselves?

I would really appreciate some data on that! Perhaps we should ask sc-users.

-Brian