Re: Documentation Translation

SCDocNode's can already be merged (this is how we mix documentation for
class extensions into the original class) - we can probably use the same
mechanism for merging primary language documents into backup language docs
(e.g. spanish -> english). This MIGHT be all that's needed. Among the other
required features, though:

1. A UI for doing side-by-side translation of docs. This shouldn't actually
be too hard, and could be written in sclang (just show a TreeView of
SCDocNode's with both english another language, where the other language
can be edited. The only challenge is automatically writing .schelp source,
which I'm not sure we have a reasonable mechanism for?
2. UI for selecting primary and backup language in the IDE.
3. Logic for indexing, loading, merging multiple schelp files based on
language settings
4. Improving indexing / loading times (doc indexing/loading is already
borderline-too-slow - this would make it much worse)
4. Possibly: an option to e.g. colorize / mark passages in the backup
language (I would imagine tight mixing of two languages would be visually
very confusing). An html style that comes from a "language" property on
SCDocNode

- S

On Wed, Apr 4, 2018 at 12:56 PM <[email protected]> wrote:

> 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
>