translating the manual

[ghost]

Not everybody understands english to a degree the manual asks for.
Although that situation has changed significantly throughout the last 20 years or so,
at least for europe i can say there are still a lot of people struggling with that.
Relying on web translators is not always a good idea since those translations
besides being super funny might add even more questions.
Seeing that there are contributors and users spread all over the world,
it should be possible to add a whole lot of languages, and make them selectable on the webpage.
So if anybody else likes this idea, i would start by offering a german translation of the manual.

[baconpaul]

That would be wonderful!

we are about to wrap up the manual for 1.9 but once that is done would love translations! Let me tag @VincyZed here who does so much of our documentation work

[ghost]

ok then i have a few more questions for you and/or vincy

• Would the updated manual be mainly additions or will it be completely rewritten?
  cause then i could start with what is there already now and update it over time.
• i would then take the Surge.md file from the manual folder in the website repo, translate it, call it Surge-DE.md and put it back into that folder.
  or is there a better way you'd prefer?

[VincyZed]

This is a great idea, though as we've discussed earlier with @mkruselj and other people, the hardest part in this process would be to make sure that every language version of the manual is updated and stays updated. For instance, if someone comes along and offers to translate the manual in some language (which we would greatly appreciate), there is absolutely no guarantee (nor obligation) that they will still be around for the next update. This would lead to some disclaimers we'd have to put at the top, for instance like "The documentation in this language may be outdated", for instance.

Another challenge would be in the case where some small technical correction(s) would have to be made. Right now it's pretty straight forward to just correct it straight away, but unless we use online translation services to help us update let's say that small part that needs to be corrected, we'd have to call everyone that worked on translations back to fix that mistake.

Speaking of online translators, I've tried feeding some with a paragraph of some pretty technical information from the Surge manual in English, and as a native French speaker, the result was surprisingly very accurate and precise. Translating larger amounts of text with online translators would of course require double-checking and corrections, but I'd say that from what I've seen it may be better that one could think, and I don't believe that only having to manually correct let's say a couple of percent of the words would be unrealistic. Although the hard part is to find translators that support large quantities of text, even automatically translating paragraph per paragraph would definitely help.

So those are the questions we've been asking ourselves for a little while, and I'm curious to hear your thoughts about those challenges. And by the way, if we end up finding good solutions to what I mentioned above and we decide to tackle translations, I'd be glad to translate to French. :)

[baconpaul]

The other thing I’m thinking is the context help url needs to be oarameterized so people could pick an alternate set. My guess is we won’t get that coded. But it’s just an xml file people could replace and we could put that in the manual

[baconpaul]

Oh and rather “may be outdated” you could say “is up to date with English manual version x” and we could even provide a way to see what changed in English since then pretty easily

[VincyZed]

Yep, that would be a better way to do it for sure.

[ghost]

Good points. I think for outdated translations one could make a difference whether it is still telling the truth and just missing additions, in which case a disclaimer would work for a while. If it is not telling the truth anymore because of changes in how things work then that translation should be disabled/hidden until it's updated again.

[ghost]

And changes would have to be communicated loudly and in time when they are being made.
I have not tried all the web translators available, one thing i have seen is they give up on line breaks and treat that as the start of a new sentence which makes for most of the fun results.

[baconpaul]

Yeah we are super good about our change cadence. For instance, right now we are in the 'last 2-3 weeks of the 1.9 cycle' so lots less dev work and lots more manual and content work is going on. Agree we will want to ask people who do translations to make it so we can reach them though for when we have additions. I can assure you the last thing you want is to read my German :)

[ghost]

The problems i see web translators having are not so much in the technical lingo being used,
online tech docs might be among their main learning resources after all,
but whenever there is a possibility of double meanings or words relying on context.

Where they definitely fail a lot is in making the right decision when NOT to translate.
Aside from all the parameters in the synth being labled in english there are a bunch of terms
where you would still want to use english terms as it might otherwise sound awkward
or be even harder to understand because noone outside of academix uses those (translated) words
which is of course unique for every language
(In that regard i think translating the UI would not be a good idea).

They also love to create dead links and mess up layouts like the tables or these things.
The better ones (like deepl or so) make all the same mistakes, just way less (than google etc.)
which in turn makes them less predictable though, making mistakes harder to find.

I think automating the translation updates with these algos can help as much as it can make it worse.
This situation might be different in 1 or 2 years of course.

Doing these translations is a bit of work the first time you set it up
and then again some with a new version coming out.
Translating small corrections to the manual in between just takes a minute.
Speaking for myself, if you notify me (in the commit message or otherwise)
there might be a delay if i am offline for a few days but that should be it.

Does github support lists for their notification system?
so you could just @ translators and everyone involved gets notified?

And should a translator for a given language disappear and noone wants to take over,
that translation disappears, which in the worst case means there are no translations anymore,
which is what we have now.

So i sent an early version, to be used whenever the time is right.

[baconpaul]

https://surge-synthesizer.github.io/manual-DE/

Wonderful

what I’ll do is make an issue in the doc repo translators can subscribe to! Once that’s done I’ll close this.

Danke!!

[mkruselj]

@mynameismuhl Just FYI, I did a number of wording tweaks on the manual, you can see my closed PR for comparison, so please feel free to update DE version whenever you can. 🙂

[baconpaul]

surge-synthesizer/surge-synthesizer.github.io#182

OK I opened that issue which we can use to keep notes and inform people so I'll close this one.

And thanks again @mynameismuhl !