Ctrl + scroll wheel, Ctrl + 0 to reset 
Hi everyone. Iām one of the translators. While translating, Iāve found some errors in the original files and Iām building a PR to submit. While at this, I realised that weāre translating the contributing branch. Iāve never used GitHub before and Iām finding it hard to understand what branches are. To which branch should I submit my PR? When I clone the project on Windows using the GitHub client, what files do I get? Are the files the same?
Hope these questions donāt require very complicated answers Thanks
I hope @gratimax can answer these questions, because I canāt. This kind of info belongs in the Original Post (and Iāll put it there when I get it). Procedure for adding translations is still a bit WIP.
1 Like
Iāll try to answer these to the best of my abilities (which admittedly arenāt very extensive since I made my first PR on Dec 31, but I try):
Firstly, what branches are. From my understanding, when you make a new branch, you take the current progress of a project, and you move it in a different direction than the master branch (think of it as the trunk of a tree, with your branch being, well, a branch). Branch branch branch. My brain doesnāt recognise the word any more after typing this paragraph.
The branch I contributed to is the master branch, and as far as I can see, thatās also the one in use for the actual docs. If the original files are what you want to change, I suggest you make a PR to that. 
When you clone the project, you get a fork of both master and contributing, as well as any branches you yourself have made. You can switch between these at will with this blue button in the upper left:
As far as I can see, changing this value actually changes the files on disk, although Iām not entirely sure how itās done. My suggestion is that you first create a PR by trying to edit a file from the master branch, then pushing that, then continuing to edit in the resulting branch and pushing those. Be sure to comment on the PR that itās not finished if you do it this way
Otherwise, you can make a local branch in the Git client (see the above image), perform the necessary changes, push your commits, then go to the web page of your branch and create a PR from there (there should be a giant green button helping you out!)
Hereās to hoping I am not in too deep, havenāt bitten off more than I can chew, etc. I think Iām mostly correct, but then again I have a way of rationalizing the most bizarre things to myself. Ah well. I hope your confusion was at least cleared a bit 
2 Likes
That was really helpful, thanks!
The only thing I couldnāt understand is why are the original files on Transifex the ones from the Contributing branch. Hope @gratimax can help me out with that doubt.
That will depend on how much you think is needed. A few pages have already been tweaked to mention Granite, and having itsā own Docs page would probably be justifiable. Where the Granite implementation diverges from the nascent Forge implementation, an explanation would be appropriate for users.
Please bear in mind that the SpongeDocs are intended to be largely implementation-agnostic where possible. Weāre providing info on the Forge implementation largely because the same team are writing it and the API. We donāt plan to provide large amounts of detail on other implementations. Preferably third-party implementations (such as Granite) can provide a nice friendly website of their own to help users install and use it, and we can put a link in SpongeDocs.
Iāll make an issue on GitHub for this (#44), so any further complications can get ironed out there.
@Dannyps Hereās the current state of things:
- The current translation sources on Transifex are those I uploaded several days ago. I did this using the transifex client(although I had to make some changes to the source to get it to upload).
- Readthedocs language handling is kind of meh. It requires us to make a separate repository for each language even though weāre using the special translation system, and it ends up looking like this. That is eww because itāll pollute up the repositories on the SpongePowered org and will need many different separate ReadTheDocs projects.
The solution to both of these problems is to set up a build system and web server ourselves to host and build the docs. Iām thinking builds would run on pushes to the repository and also daily. Hereās what would happen on a build(these commands are not exact, Iām running on memory here):
- New *.po files are generated(
sphinx-intl update -l de -l ja -l ...) - These files are synced with the transifex config(
sphinx-intl generate-transifex-resources ...) - New translation strings are pushed to transifex (
tx push -s) - Documents from the tx site are pulled down (
tx pull -s -t) - Each language would be built(
LANG=es sphinx-build -t html; LANG=de sphinx-build -t html; ...) - The directories would be copied to the webserver(or built there directly)
- Profit! New translation keys are now on transifex, documents are generated and are served up in every language
That would be performed by one of our job workers(or possibly travis). Setting up the workflow above will take a while, but after that the Sponge documentation will have awesome language support.
2 Likes
Wow, that was bold! I really though that Transifex was somehow connected to github and getting the files directly. Iāve messed around a bit with the transifex client (downloading all files of a language) and with Sphinx (building the docs, even with themes!) so I get what youāre thinking and I think that should work out just great! Thanks for your answer!
Iāve noticed that that on the Transifex documentation localisation page there are separate pages for French (France), French and French (Canada). To be honest French (France) and French (Canada) are quite similar based upon my previous experience - perhaps they should be merged. Not too much work will be lost since only French has had any work done, not French (Canada) and French (France).
I believe @gratimax prefers to use a Locale {eg. French (France)} over a root language {French} for the Docs. He just made a boo-boo when setting up French, and actually wants to port the pages to the France locale.
We donāt want to get into arguments with, for example, folks from Quebec about how their dialect varies from that of France. The real tell will be if anyone actually bothers to contribute to the Canadian version - it was requested, and it seemed reasonable. Itās not the only one, either. If it withers, it may get pruned.
I will add that we donāt want the language list to bloat too much, and the folks behind the scenes have yet to enable a system for viewing the translated pages anyway (unless youāre on Transifex).
I see. Just one question: will the French (insert locale here) be directly ported from the French and then changed by local speakers, or reconstructed from the ground up?
Rejoice, SpongeDocs Translators, Editors and Contributors!
We have a new sub-forum to ourselves!
Hopefully this will help prevent messages from being lost in the traffic.
3 Likes