Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

x/website: add support for languages other than English #21666

Open
ericlagergren opened this issue Aug 28, 2017 · 8 comments
Open

x/website: add support for languages other than English #21666

ericlagergren opened this issue Aug 28, 2017 · 8 comments
Labels
Documentation NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made.
Milestone

Comments

@ericlagergren
Copy link
Contributor

ericlagergren commented Aug 28, 2017

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 Accept-Language header or support some sort of en/, fr/, etc. URL path option.

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:

  • React
  • Rust
  • Python
  • Java (sorta)
  • PHP
  • JavaScript (via MDN)
  • Perl (third party)
  • Ruby
  • Babel
  • LaTeX
  • Scala (like how Go currently does it, but more uniform)
  • ...
@cznic
Copy link
Contributor

cznic commented Aug 28, 2017

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

@ericlagergren
Copy link
Contributor Author

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

@dominikh
Copy link
Member

How will the Go team review contributions in other languages? And who guarantees that they're kept in sync with changes/additions to the standard library?

@ericlagergren
Copy link
Contributor Author

@dominikh

How will the Go team review contributions in other languages?

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.

And who guarantees that they're kept in sync with changes/additions to the standard library?

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

@ianlancetaylor ianlancetaylor added the NeedsFix The path to resolution is known, but the work has not been done. label Mar 29, 2018
@ianlancetaylor ianlancetaylor added this to the Unplanned milestone Mar 29, 2018
@ianlancetaylor
Copy link
Contributor

CC @spf13

@ALTree ALTree added NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made. and removed NeedsFix The path to resolution is known, but the work has not been done. labels Sep 22, 2018
@bcmills bcmills changed the title docs: add support for languages other than English website: add support for languages other than English Apr 9, 2019
@seankhliao seankhliao changed the title website: add support for languages other than English x/website: add support for languages other than English Dec 12, 2022
@Sunshine40
Copy link

Sunshine40 commented Dec 13, 2022

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 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 build cmd for most of the day, and try to write a program with 1000 lines of code (by no means a huge task) which only need minor fixes before it could build and run without major bugs – that would simulate learning English without a native English speaker as a teacher.

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.
But there're far more non-English speakers than English speakers (non-native speakers counted, see: Most-spoken languages, CIA, 2020), and rendering English as an essential skill for a capable programmer is somewhat arrogant (as an English speaker, no matter native or non-native).)

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?

@Sunshine40
Copy link

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.
Apparently an automated workflow is designed to keep the translations up to date and make translation jobs easy. But these languages don’t have a documentation standard when it comes to third-party package publishment.

Go, on the other hand, has the tool to standardize doc generation if one wants to publish a package.
It looks like only one step from adding translation support similar to how they make .NET/PHP official doc internationalized.
At the current state, the absence of this part just effectively chopped the non-English speaking Go community off the English-oriented Go open source community (though technically they can publish packages with non-English doc), which is a shame IMO.

@Sunshine40
Copy link

Sunshine40 commented Dec 13, 2022

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.
Yet a good portion of these programmers are still capable of producing decent code work.

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.)
(Accessing github became a grey area from then on, and believe it or not, most Chinese find it more comfortable in a grey-area state, for no need to follow strict regulations while not getting punished)

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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made.
Projects
None yet
Development

No branches or pull requests

7 participants