Support for multiple (human) languages

[arunisaac]

It would be nice if tldr pages existed in other (human) languages too, and not just English. Is there any plan for tldr pages to support multiple languages?

[agnivade]

I am sorry, but the entire page parsing logic is based around English punctuation marks. Like :, >. We cannot fully shift to other languages. English punctuation marks are compulsory.

Just simply converting the pages to other languages is possible. Although it will take architectural changes, which need to be implemented by every client out there. So, even if we make pages in other languages, until the client you are using implements it, you won't be able to use tldr.

But more importantly, someone has to write the pages. This is the first request to support multiple languages. If there is sufficient interest, then we can decide on how to lay out the pages, and then each client can implement it gradually.

[arunisaac]

For the most part, technical documentation is non-existent in most Indian languages. And, owing to their size, translating existing technical documentation requires a lot of labour to achieve even a small degree of completeness. So, my thinking was that due to its small size, the tldr pages could be translated with less effort and quickly reach sufficient completeness to attract more translators and bootstrap the process of translating bigger manuals. There are large sections of society that would come forward to learn more about computers if that knowledge was presented to them in their mother tongue.

[sbrl]

Sounds like a great idea, @arunisaac! What architecture / folder structure would you suggest? The current structure for reference is to have a pages folder, with the individual platform folders such as common, windows, linux, etc. inside there.

[sbrl]

Just thought of this also: We'll need someone who can speak the target languages to review the PRs as we do for English. Quite often we suggest wording and grammatical changes etc. to improve the clarity of the page.

[owenvoke]

I wonder if something such as GitLocalize could help with this?

We could have it in a structure such as:

pages/
  en/
    common/
    linux/
    osx/
    windows/
  etc/

---

But yes, as @sbrl mentioned, this would require more reviewers for other languages. 🤔

[agnivade]

Breaking down into sub-folders will break all clients immediately. I would go with the usual github idiom for storing READMEs in multiple languages.

Like - <filename>_<2-letter-lang-code>.md. And leave the default as english. So that we can add new files without breaking anything. And clients can implement new language support gradually at ease.

[owenvoke]

Hmm. That would definitely make more sense. 🤔 I wasn't really thinking.

[arunisaac]

Like - <filename>_<2-letter-lang-code>.md. And leave the default as english.

This sounds great. May I send pull requests for translated tldr pages now?

We'll need someone who can speak the target languages to review the PRs as we do for English. Quite often we suggest wording and grammatical changes etc. to improve the clarity of the page.

Review is good to have. But, what do we do if somebody sends in a PR for a language with no reviewers? Will that PR be indefinitely stalled?

[mfrw]

I am not against this idea, but could you please give an example of what language you would choose to translate in? Although it has been said above in the comments, I would request some specific information. For starters I have some questions:

• What problems would the translated pages solve? Who is our target audience?

• What is the value add of translating as it would be very painful to keep all the translation copies in sync? Just as an example, what if I add/modify a page and am not able to update the translation?

Just a thought, I support the idea given you convince me to 👍

/cc @sbrl @agnivade @pxgamer @arunisaac

[arunisaac]

I am not against this idea, but could you please give an example of what language you would choose to translate in?

I would translate to Tamil, my mother tongue. It is the only language other than English that I have any proficiency in. I am ready to send in at least a few PRs the moment there is some consensus and approval for this proposal.

- What problems would the translated pages solve? Who is our target audience?

The translated pages would make computer knowledge more accessible to a large section of the population who don't have a good command over English and would learn much better in their mother tongue. Personally, for my translated Tamil tldr pages, my target audience is young people who have schooled in Tamil medium, and find the English language to be a barrier for them acquiring computer knowledge with ease.

- What is the value add of translating as it would be very painful to keep all the translation copies in sync? Just as an example, what if I add/modify a page and am not able to update the translation?

Translating and keeping the translations in sync would no doubt be a painful exercise, and require a lot of labour. But, the amount of labour that needs to be invested into translation is negligible compared to the amount of labour that can be saved for non-English speakers. Also, translations need not be immediately synced. Consider Wikipedia for example. Often, the English Wikipedia has the most up to date articles. The other languages eventually sync up based on the availability and willingness of translators. And, sometimes they don't sync and have their own unique versions of the same article. Such divergence is also acceptable. The need to speak and learn English is not going to vanish just because tldr pages are translated to other languages. And, people might still be required to learn English to acquire more advanced computer proficiency. But, if we can break down at least some barriers to knowledge access, and pique the curiosity of at least a few people, our labour is well worth it. PS: This proposal occurred to me when I was considering translating man pages. I then realized that translating tldr pages would be much easier and more worth the trouble.

[agnivade]

You can send PRs, but note that without any client support, those pages will be useless. Unless you want people to manually open github pages.

I would recommend that if you want this, fork this repo and add pages in your own repo. And also add support to the client that you are using. Clients can be configured to point to a custom repo instead of the main repo. That way, you can use a client to point to your own repo and get the translated pages.

Once we have atleast one or two clients supporting multi-language pages, we can easily shift those pages to the main repo.

The reason I ask this is because I don't want to add pages to the main repo unless there are clients which support it. Extra pages mean extra bytes that need to be downloaded when you update the client. And if those pages are useless, then those bytes are entirely wasted. Plus, we have this great feature to be able to use custom repos. So let's use that for now, and when clients start to have support for this, we can move pages here.

[sbrl]

@agnivade sounds like a plan. Do keep us up-to-date with your progress, @arunisaac! When you've got a collection of pages, perhaps we can start implementing support in some of the clients?

I am somewhat concerned about keeping 'tldr-pages' unified. It would be awkward if it turned out in the long run that we end up with an English tldr-pages, a French tldr-pages, etc.

The other awkward question is about the language of the pull requests themselves. Should we standardise on English in the pull requests - even though the page in question is actually in French? Or should we request that pull requests for French translations of a page should also be in French?

If this takes off, it might also be necessary to translate the README / the style guide / etc., but that's a whole different problem for a separate issue I think.

---

Regarding the structure, what about a structure like this:

• pages/ - Master English copy
• pages.fr/ - French pages directory
• pages.de/ - German pages directory
• etc.

Then all the pages for a language are all neatly tied together in a single directory. I wonder if GitHub let's you download a single folder as a .zip, rather than the whole repo.

---

What problems would the translated pages solve?

I think that @arunisaac answered this in this comment, @mfrw.

---

I'd love to get @waldyrious's opinion on this.

[waldyrious]

Regarding the PR reviewing process:

We'll need someone who can speak the target languages to review the
PRs as we do for English. Quite often we suggest wording and
grammatical changes etc. to improve the clarity of the page.

Review is good to have. But, what do we do if somebody sends in a PR for
a language with no reviewers? Will that PR be indefinitely stalled?

Anyone can review PRs :) I would suggest applying a similar policy to what we currently have (2 approvals by repo maintainers). The adaptation could be that, for translation PRs, if it has two approvals from two regular users other than the author (besides passing syntax checks, etc), a maintainer can merge the PR, perhaps running it by google translate to perform a basic sanity check and maybe ask clarifications. This, of course, assuming that no maintainer speaks the language introduced in that PR.

I believe this workflow would fit our current processes well, and ensure that translation PRs would not remain indefinitely stalled.