Handbook translation into different languages

[kuchikuu]

Greetings,

Current version of Docs is available only in American English.

In my opinion, people that use Void are not new to the Linux world. People that often switch from other distros usually know English in a way that they are comfortable reading manuals. But there are many people who aren't as experienced, and for some English is a wall they are unable to jump over.

That is why I am submitting this issue (feature request) to show how important it is to have docs available in multiple languages, so whoever wants to try Void won't be limited by his ability to understand English.

As stated in Handbook Style Guide:

Although there will always be cases where command listings are appropriate, the contents of the Handbook should be written in American English (or the relevant language in the case of translations of the Handbook).

So far we don't have any "relevant language" available.

People that use Void Linux, but can't code, would have a chance to contribute as a Translator. People from Spain, France, Italy, India and many other countries could team up and make Void Linux available to a bigger audience in the future.

Every person that decides to use Void Linux is precious, and we should fight for it.

I personally could help to translate the docs into Polish.

[kuchikuu]

I forgot to mention that it would be required to implement a language change mechanism on the docs website, as there is none since the only available language is American English.

[flexibeast]

Thanks for opening this issue! i'd definitely like the Handbook to be available in multiple languages. Thank you also for registering your willingness to work on a Polish translation. :-)

The Handbook is currently under heavy development - we're regularly adding new content, fixing problems with existing content, and trying to ensure the overall style is consistent. So my feeling is that it might be best to wait until things have settled down somewhat, to avoid translators having to do extra work as the source content changes out from underneath them.

i'd like input from my fellow doc team members @ericonr and @bobertlo on how we should proceed with this. Perhaps we could create an issue per translation, with a checklist of Handbook pages, maybe noting which pages are essentially finalised and ready for translation?

[travankor]

I can help with Spanish translation and seems like @ericonr can do a Portuguese (BR) translation?

[kuchikuu]

There are (at least) two ways to do the translations:

1. We could start translating now, so that translators wouldn't be overwhelmed by the amount of pages that need to be translated.

The docs, unlike a wiki, can't be heavily "incomplete".

We could translate the most important stuff (for example: general information about Void Linux, installation details, GUI & core programs) and release it. Then, slowly catch up to the American English version of the Handbook.

Any changes to the core version of the Handbook (American English version) should be mirrored to all the translated handbooks as a warning/notification, so that we can keep the Handbook up to date after any change.

This would allow to progressively implement the Handbook in different languages.

Front end of Handbook website: Missing pages would appear in red color on the list. (Similar to what Wikipedia does with the missing articles)

2. Translations start once the American English Handbook is mastered to the point that no major changes will occur.

(Translators must wait for the American English Handbook to be done, but willing translators could start doing it even now)

2.1) Progressive releases of the Handbook. This would be beneficial in order to see a translated Handbook "in action". Translators wouldn't be overwhelmed by the amount of translation that is required to release a Handbook.

2.2) Publish-once-finished method would require a specific-language Handbook to be translated entirely before being published. This assures to deliver a "complete experience" to the end user. Please take into consideration, that while this is a great approach, people using a language that is considered a "minority" in Void Linux community would suffer, for a great extend of time, a lack of a Handbook, due to lack of work force required to publish the Handbook.

In short: 2.2)Best outcome -> Possibly never released 2.1)Good outcome -> Limited by the time of American English Handbook and by the time left till it being fully completed 1)Decent outcome -> Possibly best option. Can be mixed with 2.2 approach

[flexibeast]

@kuchikuu: Thanks for sharing your thoughts on the issue space!

Something i'd like to note is that all of the people working on Void are volunteers - we're doing this in our spare time, for no pay. At the moment, the senior member of the docs team, @bobertlo, is snowed under by work, and isn't able to spend much time on Void. Further, both @ericonr and myself are spending hours each day on writing and reviewing PRs (a number of which require input from other Void team members) in addition to working on improving the docs infrastructure. i wanted to mention this so that if progress on this issue doesn't happen quickly, it's because we're juggling a number of things. :-)

With that caveat, here are some of my initial thoughts:

• i'm not sure the Handbook will be considered 'finished' in the immediate future; even though it now has a fair amount of content, there are still important parts missing, some of which are dependent on parts not yet published but still being worked on (e.g. #177). So personally, i think work on translations shouldn't have to wait on the Handbook being "basically done".

• Development of the Handbook isn't generally based on a 'release' model, although @ericonr is working on a void-docs package (https://github.com/void-linux/void-packages/pull/21453) that will reflect the state of the Handbook at particular points.

• My personal feeling is that approach 1 of your comment would be the best way to proceed; i particularly like your suggestion:

Front end of Handbook website: Missing pages would appear in red color on the list.

[flexibeast]

Another issue that comes to mind is reviews of PRs for translations. i know only smatterings of languages other than English; certainly not enough to be able to do translation reviews. In some instances members of the Void team might theoretically be able to do pre-merge reviews, but i imagine this won't always be the case ....

[ericonr]

So, regarding logistics!

I took a look at how the Rust Book does it, and they have an appendix for translations. People open issues in their issue tracker to get permission to translate and inform them of where the book is contained, then they add a link there.

The books aren't hosted in the same infrastructure, it seems, and the Brazilian Portuguese one, for example, uses GitHub Pages for hosting.

I'm not sure this is the best model, but it's probably the easiest one, given that we are using mdBook. We could even consider hosting these books in the void-linux organization, both for development and for the actual websites themselves.We could take a look at hosting options as well, obviously.

The other model is hosting development here, but then we'd need to work out how to manipulate mdBook so everything still looks good.

[travankor]

I'm not a fan of "forking" the repo for translated copies; this will result in fragmentation and in inconsistent quality standards -- these were the reasons why Void moved away from mediawiki.

mdbook's "approach" to i18n is one of the reasons why it is one of the worse options out there imo.

[travankor]

Another issue that comes to mind is reviews of PRs for translations.

As long as the reference material in English is reviewed, I don't think this will be a problem. While having peer-review is always nice, a commiter can always run the text through a machine translation to at least verify that the translated section isn't completely off course. Correctness fixes can always be merged later on.

[flexibeast]

@travankor:

I'm not a fan of "forking" the repo for translated copies; this will result in fragmentation and in inconsistent quality standards -- these were the reasons why Void moved away from mediawiki.

i agree.

While having peer-review is always nice, a commiter can always run the text through a machine translation to at least verify that the translated section isn't completely off course.

Good point.

[Piraty]

I'd say don't waste your efforts on such (in my eyes) irrelevant aspects.

1. Void doesn't target users who want an ubuntu experience and manually handling / fixing issues is expected. This requires reading online docs and man pages which are in English 99% of cases. Therefore I expect Void users to be able to understand the most basic of English (the doc guidelines already require writing simple-enough and to-the-point English syntax and grammar).
2. Translated pages are likely to rot / hard to keep in sync with the main source (English). See Arch wiki for reference.

Everybody needs to keep in mind that Void usually goes by 'upstream knows best', which means that the handbook ideally contains very little content (only Void specific) because upstream projects are considered the main source of documentation. Else we will face the same issues we (and everyone else maintaining one) had with the wiki. For easy setup guides of application X, people can still consult the Arch wiki.

Addendum: if putting some link to automatic translation engine is possible (in a privacy / user right respecting way), that wouldn't result in maintenance overhead. Yet this is something users incapable of understanding English can already do on their own...

[kuchikuu]

@Piraty

"Void doesn't target users who want an ubuntu experience and manually handling / fixing issues is expected. This requires reading online docs and man pages which are in English 99% of cases. Therefore I expect Void users to be able to understand the most basic of English (the doc guidelines already require writing simple-enough and to-the-point English syntax and grammar)."

Well... To be honest... I can't disagree.

In my opinion, just as I wrote previously, people that reach for Void Linux already (should) know English on a level that reading Void Docs shouldn't be problematic to them.

"I'd say don't waste your efforts on such (in my eyes) irrelevant aspects."

Perhaps.

I am fully aware of the situation. And again, I just can't disagree. Your points are very solid. English is EXPECTED at projects such as Void Linux.

I just thought "Hey, it would be nice to have information provided to the people that don't quite get English".

I added this issue as an idea. Whatever people-in-charge decide, I'll be cool with.

(By writing this comment, I agree that (perhaps) English docs are the only docs that we need, but if people are willing to translate, we could at least have the ability to do so. If there are no volunteers to translate, the project will simply die before it hits the daylight, but again, having the ability to translate would be a first step)

[Chocimier]

I like the idea. I do not agree that we should not translate documentation because there is too few translated documentation elsewhere.

Keeping documentation is sync is easy with po4a. It is done by creating .po files from .md files then recreating translated .md files from .po. Once original paragraph changes, old translation won't be used, but source language paragraph. Po files are only thing to keep under revision control, all other is generated.

Here is tooling - see changes in res/ - and demo - only summary translated, maybe some links broken.

I could start accepting translations in fork, and when enough content appear, we'll see if it fits into main infrastructure.

[ericonr]

@Chocimier apparently I had missed your comment.

Can you share the repo where you have this? I'd be interested in working on this as well.

[icemodding]

I can help with neutral Spanish and Latin American. :-)

[Chocimier]

Nice to see some interest.

@ericonr, it was in translations branch of my fork as linked above, but now it is on master too, with quickstart guide in readme.

[JoaoP-Vieira]

Hi, a translation of a doc is very important to approximate people to Void Linux and for Linux in general. I know, Void Linux docs are constantly changing, and this can be hard to maintain, even more with many other languages. It's been 1 year since this issue has been opened and I want to know how the Void Linux team thinks about it.

[Chocimier]

Team thinks that it is your job to translate, not ours. We will consider publishing, but there is nothing to publish yet.