x/website: add support for languages other than English #21666
Right now the docs are only in English. There's some support for languages other than English, but the wiki page is merely a footnote.
Other projects—like React—are attempting this as well. Not only does it give newcomers a (somewhat) easy way to contribute to Go, it also makes Go a more welcoming and inclusive place for non-English speakers. Obviously the English version would remain the "master" version of the docs.
Ideally, golang.org would respect the
I'm not sure how much of a proposal this needs to be, but it's something I'm willing to put further thought into if needed. (It's not a language change or anything, so I didn't write out a full proposal.)
Projects with their docs and/or websites in multiple languages:
The text was updated successfully, but these errors were encountered:
With full respect to everyone's choice of which language to use and when, in my experience using any other language than English to study programming/CS and/or learn from the documentation makes that programmer less capable on the long run - and vice versa. (I'm not a native English speaker.)
@cznic that's a good point. As a native English speaker I don't have much experience learning to program in a non-native language. Personally, I've noticed that it can be more difficult to "concretely" learn things in a non-native language. But I've also had the luxury of having most everything I needed in my native language.
That's neither here nor there, though. I don't really believe it's Go's job to require its users to adhere to what we (general "we") believe to be best practices that are unrelated to the language itself.
In this case, unless the Go team member speaks that language, they'll have to sanity check it (Google translate, etc.) Ideally, you'd have a community member double-check the additions.
IMO the best way to start would be to start on the more static parts: golang.org/, golang.org/doc/, golang.org/doc/contribute.html, etc. If that's too difficult to keep in sync or the whole thing flounders, it can be scrapped.
Alternatively (or additionally), a simple disclaimer can be put at the top of translated pages. (Like I mentioned before, English is the 'master' version.)
As an example of what the React project is doing: facebook/react#8063
@cznic While I agree with you on the less capable on the long run part as a matter of fact, unfortunately acquiring adequate English proficiency for programming doc reading and writing (writing part explained in #57254) could never be a suitable choice for everyone.
Learning a programming language takes effort, but the difficulty is lowered not only by programming guides usually more interactive than conventional natural language textbooks, but also by the toolchain giving constant feedbacks whenever you make a possible mistake.
Imagine learning a programming language without the access to an IDE or even the access to the
In comparison to the effort needed to require a whole dev team to be English proficient, translating documentation for a specific task is absolutely a more realistic. And more realistic tasks get higher chance to be fulfilled than those mission impossibles.
(Besides, English just happens to be the language with most speakers in the world, thus tech docs for international cooperative jobs naturally comes with an English version.
If, in an alternative universe, Chinese or Hindi happens to be the default language for tech docs, while English speakers still take 10% of the world, does it make sense to all these English speakers to learn Chinese/Hindi before they are regarded as capable of participating in an international cooperative job?
So my point is, English proficiency is surely helpful for a programmer to take part in an open source project where documentation other than the English version doesn’t exist yet, but the existence of proper translation would certainly help more.
And believe me, the reason why only a few open-source go projects have translations for documentation, is the lack of a standard paired with tools on this topic.
When creating a guide for an existing go package facing non-English speakers, individual work could be in the form of a blog post, or a separate doc repository. By such means, doc translations could be littered everywhere, and without version tracking.
I’ve used .NET and PHP, both come with a variation of translations of the official documentation.
Go, on the other hand, has the tool to standardize doc generation if one wants to publish a package.
Through my real-life observation, I see lots of programmers who hardly refer to English documentation. Even when they do so in rare cases, they mostly choose to use webpage translation tools.
What they use is usually a subset of publicly-available libraries, filtered by Prometheus’s who did the translation job on documentation.
What would they do when they found a bug in the package they imported, or when they’re eager to improve the functionality of the package?
Well, they might clone the repository, not from github (blocked in Mainland China), but from the local cache of the package which may come from go module proxy mirror.
Then, they do the patch on the (cloned or not) package code base. And these contributions never made their way to the official repository of the package.
Since the official repo don’t get feedbacks/contributions, version updates naturally come without them. And to avoid dealing with conflicts every time, one naturally locks the version and refuses any updates.
Such workflow just harms the open-source community as well as those developers both.
But github is blocked in China, this will not change with go doc translation support?
(Skip to TL;DR if you’re not interested in Chinese specific details)
Internet censorship isn’t that severe in China, I’ve never heard of anyone facing legal problems if he uses an internet proxy server to bypass the Great Firewall just to google random keywords (even those sensitive to CN government) and to use github to fetch/commit some random repos. (Supposedly he didn’t confess to the police about bypassing the wall, and no police officer actively asks anyone if he has bypassed the wall unless he’s suspected to be part of a cybercrime)
Basically it’s not using github that the cn gov is against, but committing to repos violating CN law is another story.
See shadowsocks/shadowsocks for example, the proxy software was so famous for bypassing the GFW that finally got attention from the CN net police.
Even this is largely officialism, and the author simply committed an empty workspace with brief explanation for removal in a new branch, stopped commiting to repo shadowsocks/shadowsocks, and the repo ceased to act as an official portal of the project.
However, repos derived from it under the name of shadowsocksr/shadowsocksrr, still lives everywhere around github and no one gets bothered by CN net police by committing to them.
(Well, it actually led to the blockage of github in the end, as the principles of CN net censorship is that if you didn’t self-censor your site, then your site would be down – either by telling your server host to shut down your site, or simply block the whole domain, which was github’s case.)
That said, the GFW’s primary goal is to prevent the not-so-well-educated netizens from viewing malicious information (in CN view) from the Internet, just like a normal firewall using stricter rules on corporate servers than on PCs (cause the network connections are usually opened consciously in the latter case). And one would be punished only for participation in spreading illegal information, not for viewing such info.
If you’re educated enough to understand how a proxy software works, and why even proxy providers to Chinese netizens implement basic self-censorship (implying the acquiesce of these services as long as they don’t help anti-China activities), you would have no problem accessing 99.9% of Internet content the same way as users from other countries do.
TL;DR: accessing github is easy for a Chinese programmer, and is cheap (proxy service basic fee doesn’t exceed RMB200/year), even if he has difficulties reading/writing English.
And there are git host alternatives to github around, which could serve a mirror to the repo. Mirrors mean more work, but syncing between git repo mirrors isn't a new thing. All that's needed is a means of contributing to the official version of the repo, instead of an unsyncable patched repo for the sole purpose of doc translation.
So why not make it easier for them (as well as programmers speaking other languages) to join the mainstream open-source community?