Translations

[alann60]

An obvious question to me is as to why translations are such a barrier. When I look at projects like Bootstrap or CodeIgniter to name a couple, they don't offer translations. You then look at WP who's codex base has translations but yet their user docs don't seem to have them.

These days if you visit a page in another language some browsers offer a way to translate the page. But then that prevents some from using their favorite browser or forces them to add plugins. Then there is a point made by @max123kl regarding differences between machine translation and human translation.

Of course, we're talking about a longstanding community that has grown the document base in the past and made massive efforts to provide translations and how would they feel if docs were English only...

Assuming we are still going along as things are re the MediaWiki, are we going with the one set of translate tags - if translators are not happy I guess they will tell us!

[ceford]

Translation is a barrier because we have hundreds of pages translated into many languages. I think we should aim to stay The Multilingual CMS. I have been looking at different solutions:

• MediaWiki is quite good for the translator but the source can become horrendously complicated for the author. It shows the translator the actual changes.
• Crowdin (I am barely familiar with) does not appear to need source markup but is line based and shows which lines are missing or out of date. It seems to break paragraphs (long lines) into sentences.
• Joomla Associations shows original and translation side by side but there is no indication of what has changed. I use something similar in a component that allows markdown format.

So I have a proposal:

1. Store the documents on GitHub in GitHub flavoured markdown format.
2. Allow direct editing in GitHub (as for the Manual project)
3. Provide a Joomla translation component (similar to Associations) but fetch both source and translation from GitHub and Commit translations back to GitHub. We could fetch the commit messages to indicate what has changed.
4. Deliver Documents with Joomla

In the past I have done most of the steps required and think I could do all of this in a few weeks.

[alann60]

The MediaWiki point you make above, I feel, will be one of the biggest reasons for many to not get involved - once you've had a go and broke a page you can quickly come to the conclusion that they are best left for someone else to update! That's not what we want.

Additions are far easier than amendments. Taking the longer view, when everything gets caught up, changes will be perhaps the greater priority but if it's not easy to do them, people may not want to bother. Makes me wonder if that's why so few are left working on JDocs.

That proposal sounds very logical to me. That is perhaps a powers that be decision first given the amount of work you would be doing?

[ceford]

A lightbulb moment! I forked this repo, made a local clone, created a German translation of Introduction with JSCodium, committed and pushed that back to my fork and finally made a pull request. As anyone who wants to contribute to documentation will need a Github account this seems a reasonable workflow.

In JSCodium I had English and German versions open side by side. And I had my terminal open to look at the change log for a specific file. So we don't need to create any new tools. GitHub and VSCode/VSCodium work fine together. And I assume phpStorm would be fine too.

[max123kl]

There is GitHub Desktop as well, even a simple editor as atom or notepad++ will work

[carlitorweb]

@ceford This is what Docusaurus do too. Using this workflow and markdown, you can get easy contributions. But as is markdown, even later we can implement something who make others not used to github, can send they contributions in a markdown file (just thinkink loud)

[carlitorweb]

This is the best of markdown. If we implement the documentation using a global syntax like markdown, is very easy implement or use any tool at our hands.

[max123kl]

@carlitorweb You have misunderstood, we were talking about the local client (on your own machine) which is used to make commits to any repo on GitHub.

[ceford]

I tried the GitHub Desktop - it is VS Code and looks good. However there was no Pull Request icon and I could not find a way back to the web interface other than the browser Back button. Ah - I needed to be in my own repo to get the PR icon.

[max123kl]

Ifyou want to get more information about Git/Github see https://git-scm.com/book/en/v2
Appendix C has the most important cli commands listed

[carlitorweb]

All you need is inside vscode, in the git tab in your left panel. For this workflow, is enough what you have there.

[max123kl]

@carlitorweb An alternative to VScode is VScodium, or PHPstorm or any code editor you like. My link shows the cli commands for your local Git if you can't/won't use a gui client.

[ceford]

I quickly gave up on Desktop. It was not clear what it was supposed to do. Local VSCodium or github.dev are both fine for me. I have referenced git-scm in a tutorial but it was useful to be reminded - I re-read the Appendix.

[max123kl]

I started on Win7 with Desktop as it was proposed by GitHub. When I switched to Debian, there is no Desktop and I have to find something similar. At least my choice is VScodium