search

RefugeRestrooms / refugerestrooms

REFUGE restrooms indexes and maps safe restroom locations for trans, intersex, and gender nonconforming individuals.
http://www.refugerestrooms.org
GNU Affero General Public License v3.0
894 stars 261 forks source link

Spanish translation #413

Closed Intimaria closed 6 years ago

Intimaria commented 6 years ago

Context

Summary of Changes

DeeDeeG commented 6 years ago

Thanks again for submitting this. Of course all of us here are figuring this out as we go, but having something to start from (like this PR!) will definitely help move things forward. I'm taking a look at the error messages...

The translations/locales aren't being found/used yet by the app, including the new "EN-en" locale. So a lot of phrases that rely on the translation system already (someone was thinking ahead?), are now saying "translation missing". The errors actually have to do with expected English phrases on the various pages not being found.

Example:

Here the automatic test wants to try to submit a spam-like restroom to Refuge Restrooms...and the test tries to click a button with the words "Save Restroom" in it...

  Scenario: Block a spam submission            # features/submit.feature:8
    When I submit a spam restroom              # features/step_definitions/submission_steps.rb:17
      Unable to find visible button "Save Restroom" (Capybara::ElementNotFound)
      ./features/step_definitions/submission_steps.rb:26:in `/^I submit a spam restroom$/'
      features/submit.feature:9:in `When I submit a spam restroom'
    Then I should see a spam rejection message # features/step_definitions/submission_steps.rb:38

but it actually says "translation_missing," not "Save Restroom"

screen shot 2018-01-08 at 16 44 19

We just need to figure out how to load the translations in properly and the errors should all be fixed. And we probably want to find a way to run the automatic tests with different locales set.

Intimaria commented 6 years ago

Oh - that makes sense. Perhaps it would be wise to hold back on organizing them into folders for now and just have all of the translations in locale folder. Or at lesst the original english versions ehich would be the logical thing to do. I think I’ll read documentation on best practice and try again! (prob should have done that before hand 🙄) Thanks!!!

Intimaria commented 6 years ago

sorry about typos writing from my phone. Thanks again. Will look into this asap.

DeeDeeG commented 6 years ago

Hi again,

I have actually been working on troubleshooting this, and I have to admit I am learning most of it from scratch. Anyways, I have been following this guide as closely as possible: https://phraseapp.com/blog/posts/rails-i18n-guide/

I now understand how to include the files even in subdirectories. In my testing so far, that makes the errors go away!

To see what I did, here is the commit I posted on my working branch: https://github.com/DeeDeeG/refugerestrooms/commit/5e1506934c2a32ae57eb9dda4b5833f0b4e8a4f9

I think the subdirectories are a nice organizational tool, so if you are just as happy to keep the new subdirectories as they are, this should do the trick. If you like, you can copy the changes yourself, or since I am a maintainer, I can even push that change to your branch.

Anyway, once we're past this small hurdle, I think (if I understand correctly) we'll be more than half-way to working translations.

Intimaria commented 6 years ago

Hi, this is awesome! Thank you for taking the time to investigate! This is a great learning curve for me. I will take a look at the options you mentioned. I'm not sure what's the best practice for work-flow. Am gonna try it out a bit and see. If I have any problems I'll let you know!

Intimaria commented 6 years ago

Yay! Checks have passed. Whew.

DeeDeeG commented 6 years ago

Way cool, this is working now.

Well, the translations can be merged into the repo, and our tests all pass, which is the major first step, but we apparently still have to teach the app to know when to switch languages. I tried loading this branch of the app in Vagrant [steps here], and then visiting the site with Firefox having the es-ES locale set (from [here]), and the site just gave me the default language, i.e. English.

refuge_firefox_es-es

I still think we're more than half way there, so once we figure out those next steps, we should have Spanish up and running. And as @cllns mentioned in #396 it would be very easy to add translations for other languages at that point.

(Do you prefer we merge this Pull Request now, and start another issue/PR for teaching Refuge to switch languages? We can try to work everything out in this PR if you want to make sure it all works 100% before merging your translations. Not sure how tricky that will be, but I think we'll figure it out. Thoughts @tkwidmer, @mi-wood, @cllns?)

(Again, very glad to have your contribution, and I'm glad to know the learning curve is right. I think we are always glad to see folks learn, and I know I learned much of what I know about Refuge's technology while working through issues on the issues page!)

mi-wood commented 6 years ago

Can we get a second person who knows Spanish to take a look at this? I’m good with merging after that and having a separate effort for detecting browser language.

Thanks both of you for the work!

DeeDeeG commented 6 years ago

@MatheusFreitag, I know not everyone not many people in Brazil [speak] Spanish, and most people speak Portuguese, but if you do happen to speak Spanish, would you be interested in looking at the translations here and proofreading them?

We do like to try and have everything cross-reviewed before posting it to the app and I'm not really sure how many people looking at our GitHub page can speak Spanish.

In any case, if it comes down to it, a few hours going over it in Google Translate (and isolating shorter phrases that way) would be able to show word-for-word what the translations say, so it's not impossible to have a reviewer who doesn't speak Spanish well... I kind of understand Spanish when I read it, and Google Translate would help me to be more confident.

Looking beyond this PR: There might be languages where we can't find a second reviewer, so having a reproducible process for that scenario seems like a good idea IMO.

Intimaria commented 6 years ago

Maybe it needs an in-app a language switcher? I'm good with going with whatever is best for the progress of the app! It would be great to have someone take a second look at the translations. Portuguese is different but closer to Spanish than English is and generally it is quite easy to read one if you know the other as they are both of Latin root. I have used gender neutral language which is hard with Spanish as the gender binary is embedded in the grammar. I have in one or two occasions resorted to using the generic 'e' (i.e. latine instead of latina or latino, avoiding using x as it is not screen readable) and everywhere else resorted to plural gender neutral work-arounds. I also must clarify am native in Argentine Spanish, but did my best to be as neutral as possible and avoid regionalisms.

Intimaria commented 6 years ago

@DeeDeeG Am still tring to find a way to install vagrant/ vb in my very old mac without it crashing :( so wasn't able to test in my local environment.

DeeDeeG commented 6 years ago

@Intimaria sorry to hear about the crashes. Thanks for trying to test on your machine. I wonder whether you have an Intel or PowerPC mac? And what version of OSX/macOS it has?

It might work with an older version of Virtualbox/ an older version of Vagrant from around the time your version of OSX was discontinued.

Beyond that... I know of a solution that might work, but it would be about ten times as much effort... I mention this not because it's a "very reasonable" solution, but because it's "a" solution.

If you have a lot of free hard-drive space and an empty 2GB+ USB stick, you can install Linux alongside OSX, and run Vagrant from Linux. (I use an old netbook that had Windows on it, but now it only runs Linux, and that has been working fine so far. I think most of the contributors/team here use mac, but a few use Linux.)

Here is a guide for installing Ubuntu alongside OSX: https://www.lifewire.com/dual-boot-linux-and-mac-os-4125733

I would call that a weekend project, because it would probably take a while to get through it for the first time. No obligation to do it, of course, (nor do I know for sure whether it would work, depending on how well-supported the particular model of mac you have is with Linux.) I just thought I would mention the possibility of doing it.

Weirder suggestion, but with less risk of overwriting your existing data: If you can get virtualbox running on your mac... you can install Ubuntu in a virtual machine, then boot into that virtual machine and install Vagrant/Virtualbox on it. The performance might be really bad, but again, these aren't supposed to be "reasonable" soluions, just the ones I can think of. Guide to get Linux instaled in Virtualbox on a mac: https://www.engadget.com/2009/09/07/how-to-set-up-ubuntu-linux-on-a-mac-its-easy-and-free/

All told, we definitely understand if the machine you have isn't able to run the test setup. Vagrant and Virtualbox are each a little fiddly to get working. I have a computer with Windows Vista that just totally refuses to run Vagrant whatever I do :/

Intimaria commented 6 years ago

@DeeDeeG I have mid 2010 intel macbook pro - was on yosemite, because of the big scary viruses have updated it to 10.13 high sierra and knock on wood it keeps working - seems OK so far. This model has a weird EFI issue which doesn’t allow for an easy time with dual boot (have spent a few weekends trying, lol), and is having some constant kernel panics whenever it has to use the nvidia graphics card so have to do some frantic switching around and use only certain programs, but there’s life in the old dear yet! I will have access to a machine running linux very soon so I will attempt again at that stage, and wow - thanks again for all your input!

stardust66 commented 6 years ago

@Intimaria You could also set the environment up manually if you're okay with doing a bit of work.

Assuming you have homebrew, you can

  1. Follow this guide to get rbenv: https://github.com/rbenv/rbenv#homebrew-on-macos. It lets you have different ruby versions for different projects.
  2. Go to refuge restrooms directory and do rbenv install to get the right ruby version locally.
  3. Get bundler with gem install bundler.
  4. In the refuge restrooms directory, run bundler install to get ruby dependencies.
  5. Get postgresql database with brew install postgres. Follow this guide: https://launchschool.com/blog/how-to-install-postgresql-on-a-mac.
  6. In the refuge directory, run rake db:create:all and rake db:migrate to create and set up the databases (there's one for development and one for testing).
  7. Run rails server and the site should be up!
Intimaria commented 6 years ago

Yes! @stardust66 I have set up a rails based local server in my computer before, so that should work! Thanks for that advice. I will check out how I set that up previously so I don't install things that might clash with what I already have going on :)

DeeDeeG commented 6 years ago

When looking at @stardust66's PR over at Intimaria/refugerestrooms:#1, I noticed that we have some pages that aren't translation-ready.

We need to update:

That would involve taking "hard-coded" sentences and phrases and moving them into a [something].en.yaml file, then updating the actual pages to refer to translation strings in place of hard-coded phrases. In other words, expand the existing translation system to also cover the pages I mentioned.

DeeDeeG commented 6 years ago

@Intimaria I think it would be good to set up the locale sub-directories in the main develop branch before any other new translations come in. If you would like, you can move the creation of the subdirectories out to another PR, so you can still get credit for setting that up. I hate to take credit by re-doing the work with a different commit-author without asking. It's up to you, though, and if it's more trouble than it's worth to add another PR for the sub-folder system, I can do it and give credit in the commit message, or try to cherry-pick parts of this PR to make it happen.

DeeDeeG commented 6 years ago

This is going to be a long comment about unimportant stuff, but the locale codes in this PR are a little peculiar. I've been seeing a lot (maybe too much? :P ) of these codes when reviewing #420 and working on #419... and so I'm getting them burned into my brain a bit. Anyway:

Here's the official format for these codes: language-REGION. (And here's a list of all the ones we can use.)

So, currently in this PR we have spanish-SPAIN (or more like español-ESPAÑA)

and english-ENGLAND? (not an official language-region code, even though it seems intuitive that it should be. The closest official thing to that would be en-GB for english-GREAT_BRITAIN)

Since most developers of Refuge thus far are United States-ians (at least the ones who wrote text into the app), our English is probably pretty safely of the en-US variety, however it also works as a generic en English for all English speakers I guess.

The Spanish, given how carefully you've avoided regionalisms, is probably pretty safe to categorize as a generic es Spanish. If you feel it's closer to Argentine Spanish, we could label it as es-AR. (There is also an es-419 locale referring to "Spanish appropriate for the Latin America and Caribbean region," but I don't think anyone will ever request that?? Who ever heard of "UN-defined Region 419?")

So in short, we should probably switch the files/folders to be

(I think the solution in #420 is capable of ingoring the REGION part entirely, so I don't know if it matters. I expect for a user-operated language-picker it would all be manual, so the codes aren't important as long we know which one is which.)

Intimaria commented 6 years ago

Hi - thanks @DeeDeeG , so much to comment on. I'm a bit lost to be truthful but am getting there. Thanks for the patience. 1.

So in short, we should probably switch the files/folders to be en, or en-US es, or es-AR

I'm glad you pointed out the folder names as this was going to be my next question - what would you prefer to call the folders? And, also, how relevant do you feel regionalisms may be in regards to the users (also projecting into the future)? I think I used quite generically named folders as a starting point, based on my experience translating in wordpress, and you make a good point re en_EN - it is not in fact used in that format in rails and so it should be changed. Regional clarifiers may be useful in the long term, if more translations come in that are region specific. I'm happy to go with what you prefer, as long as they default to the main language when needed. In fact, as you mention, it could be that just es and en is OK.

2.

I think it would be good to set up the locale sub-directories in the main develop branch before any other new translations come in. If you would like, you can move the creation of the subdirectories out to another PR

OK, I'm happy to do this, but am not sure about the work-flow. I can give it a go in order to learn, as I really want to learn git better, but if I can't get it right I would be very happy for you to do it, credit or not. I understand I need to make a new branch - with the folders (without the current translations added?) with the correct names, en, or en-US es, or es-AR. I'm a bit new to this and appreciate the learning experience. If you have patience with me I would really like to try this as it's something I haven't done before. I am doing everything via terminal so I don't really have a visual cue to what needs doing as it unfolds. I am reading a lot of new stuff as I go, but I don't have a lot of spare time so I am glad for the good vibes.

  1. We need to update: the "splash" page (homepage), the Contact page, the search results page, the nav bar (at the top) the footer search bar buttons ARIA labels (probably) and if somehow possible, the API documentation page.

Is this something I need to do right now or is that something that needs to be done previous to my translating them? Does that need to be done in this PR? If this is done I am happy to supply further translations.

DeeDeeG commented 6 years ago

Whoops, I may have info-dumped a bit excessively in this Pull Request. 😅 (I tend to do that!)

  1. I think es and en are fine. If we ever get multiple regions of the same language, we can split it up later. Those (es and en) will definitely work, and that's all that actually matters for the moment. (Whew.)

  2. See comment below...

  3. The splash page, Contact page, etc. will be translation-ready soon, hopefully by the end of the weekend. I already finished the splash page here. I was going to do this work myself, and submit that as a Pull Request against the main develop branch. (if anyone gets to it before I do that's fine also!)

DeeDeeG commented 6 years ago
  1. You found the right person! I am totally down to teach you or anybody the git commands. I think Git is a really good system, once you learn it, but I will openly acknowledge the learning curve is ridiculous.

I understand I need to make a new branch - with the folders (without the current translations added?) with the correct names, en, or en-US es, or es-AR.

My idea for this new pull request was to prepare the main develop branch to receive new translations in an organized way, with the sub-folders and everything. So I envision it would:

I will also try to give some info on the git commands that would be useful for this. (See below):

There are a lot of resources listed here on our "wiki", by the way: Newcomers' Guide#further-learning-about-git

Especially this cheatsheet if you are short on time: Spanish, English

The most helpful thing for me is to know what branch I am on, and what's up with that branch:

Changing branches is done with git checkout...

If you ever need to delete commits, you can use git reset.

And of course, the basics, which I'm pretty sure you already know:

Managing branches...

Intimaria commented 6 years ago

Oh wow, so much new info, thank you! I found this guide via your links which I love because it's for somewhat experienced beginners like me. Most guides assume you're starting from zero and don't account for some of my actual questions lol 💯

So, I made a new feature/lang_folders branch and initiated pull request #422

But the application.rb file shows conflicts both there and here - I tried updating it manually to what it is on the main branch. I seem to be missing a step, perhaps am not fetching upstream content correctly or missing something. Either I'm not sure how to pull from the new changes from the main upstream branch or am not doing it right. Is git fetch upstream right? I don't know why it isn't incorporating all the new changes.

Have been able to install vagrant and virtual box in a friend's mac, so will attempt the testing as soon as I can.

Intimaria commented 6 years ago

Also, about and business info sections are already translated in this PR. 👍

DeeDeeG commented 6 years ago

Thanks for the continued work, and congrats on the learning! I am very busy this morning, so I will try to take a real look at these commits later, but I am glad to see all this progress coming together. Very glad to hear the resources in the wiki were helpful! (Think-like-a-git is definitely one of my favorite guides for Git!)

DeeDeeG commented 6 years ago

A quick maybe not so quick how-to on managing remote branches (I learned the basics of this here, of all places.)

  1. git remote add [URL-of-Git-repo] [any-name-here] to give the remote repo a nickname in your local git folder.

    • An example: git remote add https://github.com/refugerestrooms/refugerestrooms refuge
    • or git remote add https://github.com/deedeeg/refugerestrooms deedeeg

  2. git fetch [remote-nickname-from-step-1] to pull in the latest commits from the remote. (updates your local folder's idea of what's up at the remote branch) (can do this any time to get latest updates from the remote)

  3. git checkout [remote-nickname-from-step-one]/[branch-name-from-remote] to copy one of the remote branches as a local branch. Optionally, add -b [custom-name-for-local-branch]. Useful if, for example, you already have a develop branch from one remote, but you need another develop branch from a second remote. Just name the second branch [remote-nickname]-[develop] and they won't conflict.

  4. On a branch checked out previously from the remote: git branch --set-upstream-to=[remote-nickname-from-step-1]/[name-of-remote-branch-you-checked-out] to make sure your local branch and the remote branch are sort of linked up.

    • This lets you run git pull in your local branch to fetch (and attempt to merge) all the latest updates from remote.
    • whenever I need to push my changes, I just push to the full GitHub URL, since I'm not aware of another way (though there is probably an easier or more-automatic way). . . on a branch I want to push to GitHub: git push https://github.com/[account-I-want-to-push-to]/[repo-I-want-to-push-to]

Bonus commands:

Intimaria commented 6 years ago

OK, thank you for continuing to help. And I really appreciate it! Am also a bit busy this w-e so will check back in a little while. I will have a go at those commands as and when.

Intimaria commented 6 years ago

Should I try to simplify some of the commits here too, as in #422?

Following from the instructions there, and fiddling about a bit, I've made my local develop branch a copy of the refugerestrooms upstream in it's current state.

I also made a local version of the feature/lang_folders for #422, and just for safety I copied the translations that I did for this PR, which were in my local develop branch, into a branch called "Spanish".

(I ended up having to do the changes in #422 a little bit differently to your instructions as I was getting some error messages, but it all ended up fine and I learned a bit more along the way. Like for instance, git makes it easier to configure a local branch to push to a specific remote branch if your working branch and the remote branch are named the same. So local working branch for #422 which was called "folders" didn't want to push to feature/lang_folders, until I renamed it the same and git made the magic happen.)

I wonder if I should ask more questions 🤣

Some of my doubts...

  1. smaller niggly doubt: You say: git remote add [URL-of-Git-repo] [any-name-here] to give the remote repo a nickname in your local git folder. When I originally added the remotes, I didn't add folder names at the end so I don't really understand if I can do it again adding folder names or if it will just get messy. 🤦‍♀️

  2. bigger more relevant doubt: In regards to this PR, following your instructions in #422, I now have a local branch called develop which is aligned with the refuge restooms current state. It doesn't have the translations in it anymore. Those are now in my local Spanish branch. I want to just add the translations to that now "clean" develop branch and push to my own develop so that it is all aligned and easy to get going and there are less commits on this PR. Is this a good idea? Should I just move them manually in my local environment or is there a more convenient way for everyone. Is this even a good idea? 🤓

Thank you so much for your committed and ongoing support!

PS: this answer from here helped: this command git remote show origin shows which local branches are pushing and fetching with which remote branches. 


Local branches configured for 'git pull':
    develop              merges with remote develop
    feature/lang_folders merges with remote feature/lang_folders
  Local refs configured for 'git push':
    develop              pushes to develop              (local out of date)
    feature/lang_folders pushes to feature/lang_folders (up to date)
DeeDeeG commented 6 years ago

[Edit: Oh my, this comment is so long. How about a summary:

Simplifying this PR sounds like a good idea.

Any way that works to do so is fine. You may even start a new PR if you find that convenient. We'll work with you and try to be helpful regardless.

Okay, original comment is below.]

Should I try to simplify some of the commits here too, as in #422?

Sure, that seems like a good idea.

smaller niggly doubt . . .

That's fine, and you might find that dealing with this is surprisingly easy. When you add a remote without a nickname, it gets a default nickname, I think.

Anyways, no worries. You can delete a remote and re-add it with whatever nickname you want.

(About remotes: Just so you know, adding + fetching remotes is a lot like making sure your local folder "knows about" a remote repo. It lets you have access to the remote repository's contents (by keeping a local copy), even if you lose internet connection. Your local branches and the remotes you add are, by-and-large, kept separate. Remotes don't affect your branches unless you tell them to, and remotes only affect local branches at the moment when you tell them to. And getting rid of a remote does not change commits on local branches.

The only work you might have to do if you delete a remote is re-configuring some of your local branches to track a remote again, so you can conveniently push/pull to that remote from your local branch. Configuring which remote a local branch tracks is done like this:

(And in a pinch you can just git pull [URL] or git push [URL], so you can get by without doing any commands to manage your remotes.))

bigger more relevant doubt . . .

From what it sounds like you are saying, this makes perfect sense to me. If you want to change your own develop branch so that it starts over off of the clean develop branch you now have from upstream, go for it. That really does simplify a lot of things.

(Long aside:The choice here, from my perspective, is whether keep going in this PR, or open a new PR, since an existing Pull Request on GitHub can't be switched to point to a different branch than it originally pointed to. In other words, if you want to keep all comments about this work in one place, PR #413, you would have to do the work for this PR in your develop branch.

(Well, this could switch to being merged into a Spanish branch or similar at upstream, rather than develop at upstream. So there's that.)

On the other hand, I would normally encourage someone to begin a new separate branch (branching off from upstream develop) for each Pull Request. That keeps develop free to track upstream. You can still start a new branch if you want. You would just need to open a new pull request pointing at that new branch.)

(Getting a little philosophical here: It's not a big deal. One of the weird things with Git and GitHub is there are always 10x more ways to do something than anyone strictly needs. It can feel (and become) complicated just because there are so many options. In the end, people just end up finding/doing something that works for them, and it works out fine. As long as what you're doing is working, and your brain isn't telling you "there must be a better way!", you can just do what you're already doing.)

(A heads up: This branch may need to be reworked again some time in the future, to take advantage of other PRs for supporting translations, such as #420. So I hope you don't mind the complexity and needing to keep updating things! Generally speaking, as long as your translations are safe somewhere, you won't have to worry about losing progress. And things ought to settle down soon, in terms of other PRs merging into develop. And we'll always figure out a way to make it work.)

Thank you so much for your committed and ongoing support!

You bet! 👍 🎉

Intimaria commented 6 years ago

Thank you! I'm still very blurry on merges. All of the below is asked without a real understanding of how git tracks changes or merges things. Don't feel obliged to explain everything right now, as I think I will be learning this as I go along, unless you feel like it and have time. The most crucial thing to me is figuring out which of the below options is perhaps best practice and best in the long run.

This what I understand might be best from your comment:

Based on me having originally started this PR with my develop rather than a specialized branch...

If I push my local develop branch to my remote develop branch, to clean it up a bit, update it with the current updates so it reflects upstream, and then push my Spanish branch to my remote directory so I have a new remote branch calledSpanish, I could - start a new PR with the Spanish branch. This seems like the neatest option from everything you said.

I could then keep my develop branch updated with the new changes in upstream that get merged from the current PRs and it easier to work in a more efficient way with upstream changes as they come.

(My local Spanish branch is essentially Intimaria/develop with translations copied into it. I have another branch which is where all the commits and things that are here in this PR now live. And is now kind of defunct locally since changes in #422 . Not sure what to do with it, it's just sitting there but thought I'd save everything just in case. )

However....

If I for whatever reason wanted to keep this PR (maybe because it's got so much good information in it 🤣 ), this is where all the questions arise as I did a PR from my develop branch & this perhaps complicates things a bit.

So for instance,

DeeDeeG commented 6 years ago

This what I understand might be best from your comment:

Based on me having originally started this PR with my develop rather than a specialized branch...

If I push my local develop branch to my remote develop branch, to clean it up a bit, update it with the current updates so it reflects upstream, and then push my Spanish branch to my remote directory so I have a new remote branch calledSpanish, I could - start a new PR with the Spanish branch. This seems like the neatest option from everything you said.

I could then keep my develop branch updated with the new changes in upstream that get merged from the current PRs and it easier to work in a more efficient way with upstream changes as they come.

(My local Spanish branch is essentially Intimaria/develop with translations copied into it. I have another branch which is where all the commits and things that are here in this PR now live. And is now kind of defunct locally since changes in #422 . Not sure what to do with it, it's just sitting there but thought I'd save everything just in case. )

I agree with everything you say here. It all makes sense to me, even having the sort-of defunct local branch, given the circumstances.

However....

If I for whatever reason wanted to keep this PR (maybe because it's got so much good information in it 🤣 ), this is where all the questions arise as I did a PR from my develop branch & this perhaps complicates things a bit.

So for instance,

  • Could I push the two branches to remote as per above, but then merge the changes from Spanish to my develop branch? That would keep this PR active as it's based on develop, but my develop branch would not reflect the upstream anymore.

You could, and that's correct about not matching upstream anymore.

And I don't know if it even makes sense to do this. I'm not sure at which point a merge is useful.

Okay, well... It's all going to involve some work if you keep the original commits. However, if you use the simplified commits in your Spanish branch, there shouldn't be as many merge conflicts going forward. Given the simpler commits:

[Edit to add: As long as there are no merge conflicts, there is no need to keep up to date with upstream develop, as GitHub will merge it smoothly when we accept this PR.]

  • If I wanted to keep this PR is it better to just directly push my local Spanish branch to the remote develop branch rather than merging them in the remote?

Pushing a branch to your GitHub copy of develop should be simple. Any sort of merging might get complicated, but is potentially doable.

I have to admit, I dont understand the phrase "merging them in the remote."

If you mean: "Do a merge locally, from one branch into the other, then push that merged result to your GitHub develop branch," sure that sounds okay. Merging, in general, might give merge conflicts, but if you can resolve the conflicts, there is no problem.

If you mean "using GitHub.com to merge the two branches," I guess merging two of your own branches using GitHub.com is possible? But I haven't tried it. You could run a Pull Request from your Spanish branch into your develop branch. I think GitHub.com will then give you a button near the bottom of the PR page to help with resolving merge conflicts, bringing you to an online text-editing interface for all the files.

I have a huge post getting into explaining merging and related techniques, but I thought I'd focus on your actual questions first! I do love getting into the technical details, as you might have noticed! See comment below for all kinds of tech stuff about kinds of merges.

DeeDeeG commented 6 years ago

[Here's as summary, before I post this:

The simple way to get compatible with upstream develop is basically what you did in your Spanish branch.

Other stuff, such as mergeing, rebaseing, and cherry-picking are gone over in this post.

Full post below.]

Well, it seems like explaining more of some basic concepts more clearly could be helpful here.

About commits:

The first commit in a repo "adds" all the files that are in the repo at the time of the first commit.

Every commit after the first commit must be a set of changes to those existing files, and/or must add a new file, and/or must delete an existing file. ("empty" commits are possible, but they're pointless.)

Fun fact: every commit contains a note of what commit(s) it is based on top of. (Regular commits are based on top of the previous commit in the same branch. Special "merge commits" are made when you do a complex merge; Merge commits are listed as being made on top of the two commits, one at the end of each branch, at the time of the merge.) Every commit has a chain of ancestors back to the first commit in the repo. Each commit is just a change on top of the state of the repo represented by its "parent" commit.

[Edit to add: The whole file is never stored on disk, unless it is a brand-new file (or a "binary" file like a jpeg, where storing "just the changes" is not technically efficient.) Instead, "only the changes" are stored with each commit. That means, when you first clone a Git repo, it must reconstruct every file starting back at the first commit! That is to say, having just the most-recent commit would give you an incomplete picture of the repo. The only way to get the complete picture is to start from the beginning (the initial commit) and work through every additional commit until the end of a given "branch". At that point, a complete picture, as it appears for that branch, is formed.]

About merges:

A merge is designed to take one branch, and merge all its changes into a second branch.

When Git merges, it first takes both branches back ("rewinds" the state of the repository back in time) to whatever commit the branches are both based on (however far back that may be).... Then, Git tries to apply the changes (aka commits) since that time from both branches simultaneously! If there are changes to one file in both branches, with different results, you have to go in and manually tell Git what to do to "resolve" the conflict. (I recommend Atom for this, if you ever run into a merge conflict and want to try to fix it. That is a text-editor made by GitHub's programmers, designed to understand and work with Git repositories. If you do use Atom, make sure to click View -> Toggle Git Tab to show the Git panel.)

I went a while before I felt like I could confidently resolve a merge conflict. It is a more-advanced thing, so there's no expectation of flying through advanced maneuvers right away. It will come with time, I expect.

Something slightly easier might be to rebase, instead of merge. (Whichever generates the fewest merge conflicts is what I'd call easiest.)

About rebase

Rebase is like a merge, in that it rewinds your repo back in time to an earlier state, then "replays" your commits.

Rebase is simpler than a regular merge, though. First, rebase looks for the commit that is the two branches' most-recent-common-commit. Then it applies the whole set of commits from branch "B". Then it attempts to replay everything past the most-recent-common-commit from "branch A" on top of the last commit of "branch B". This makes it look like you started work in branch "A" after all the commits in branch "B".

So if you rebase Spanish, for example, on top of an up-to-date copy of upstream develop, it will be like you started work in Spanish after #420 was merged. [Edit: I mis-read your comment, so this crossed out part would not be a good example.]

You can still run into merge conflicts, though. This is just designed to be a slightly more simple way to "replay" commits compared to a regular merge.

Even simpler than this would be "cherry-picking"

About cherry-pick

Cherry-pick is a tiny little self-contained rebase. It "rebases" one commit after the end of your current branch.

git cherry-pick [commit-ID] takes the changes in that commit (no matter what branch it's on, so long as you have it in your local folder somewhere) and applies it on top of the current branch.

(Note: the new, cherry-picked version of the commit gets a new commit ID, which makes it unique from the original commit. This can cause a hassle (merge conflicts) if both versions of the commit are merged into the same branch. One you learn how to resolve merge conflicts, this becomes "not a big deal.")

not-so-fun-fact: Even just cherry-picking one commit can cause a merge conflict! The changes in the original commit may conflict with changes you've made since your branch's and the original commit's most-recent-common-ancestor.

The only way that guarantees no merge conflicts:

The only way to avoid merge conflicts is to not rebase, cherry-pick, or merge.

(This sounds like what you did in the Spanish branch.)

To do so, just copy the files that you worked on in one branch somewhere else for safe keeping... preferably outside of any Git repository or Git folder.

Then get on a branch matching upstream develop, copy the files into your working directory, git add them and git commit them.

Strategies for a long-term workflow

The most crucial thing to me is figuring out which of the below options is perhaps best practice and best in the long run.

The sort of "industry best practice" most people agree on is:

You can optionally do some other things, if you feel like it:

And in general, frequently branching off locally and trying merges can be helpful. If you do all the crazy merge experiments in a separate branch, you can keep your work safe in other branches. If anything goes wrong with the experimental branch you can just delete it.

tkwidmer commented 6 years ago

Thank you to all that are working on this project. <3 <3

Intimaria commented 6 years ago

OK - am going to read carefully through all of this and do the work on it tomorrow! Thanks so much @DeeDeeG !

Intimaria commented 6 years ago

OK, maybe in a rush to try things out today when I have time I accidentally closed this so have started a new PR as referenced earlier 🤦‍♀️ 👍 EDIT: It closed when I pushed a clean develop branch into the remote develop.

ashishwadekar commented 6 years ago

Great work @Intimaria 👍 This will make it easier to add a further translation in different language.

Working on your efforts I would like to add the translation of the Hindi language.

@DeeDeeG Will that be ok? Should I raise an Issue first in refugerestrooms ?

Cheers, Ashish

Intimaria commented 6 years ago

Hi @ashishwadekar, thank you! It's really thanks to @DeeDeeG and others that the files are now fully translatable! Check out #421 as well as this PR for a fuller understanding of the process.

Considering what friends in the LGTBQI community in India tell me (been following the conversations around Section 377, as well as discrimination towards Hijra community), I believe that it would be a great really helpful have a Hindi translation.

DeeDeeG commented 6 years ago

Yes, we would be very interested in a Hindi translation!

You can file an issue if you want, just to make it more clear that you are working on this.

But mainly, having your translation in a Pull Request would be the most important thing. All the maintainers/ contributors who can help out will take a look at it as soon as they get the chance. (We are all volunteers, by the way, but we've been doing a pretty good job of responding quickly to questions and concerns as of late.)

The part that may take the longest before your translations are merged in is getting another person who reads Hindi to review and give feedback on the translations. (Or if someone can review the translations quickly it might be the fastest part of the process, I suppose...) But really, I think we would be glad to have that translation, so thank you very much for asking about it, and we give full support.

[Edit to add: If your run into any problems, or if you have any questions about the process, let us know and we will try to help you out.]

(I speak for myself, in that I know I'd be glad to have this translation. We do have two other active, core maintainers, and I don't see why they would be anything other than super excited about this. But If there are any concerns/comments, open to further discussion, @tkwidmer, @mi-wood.)

ashishwadekar commented 6 years ago

Hi @Intimaria & @DeeDeeG

Thanks for your warm response. I will start by adding an issue for more clarity.

Considering what friends in the LGTBQI community in India tell me (been following the conversations around Section 377, as well as discrimination towards Hijra community), I believe that it would be a great really helpful have a Hindi translation.

@Intimaria It will be a pleasure to help out the LGTBQ community in India in some way via this effort 😇

Also, I will start by forking @Intimaria s Spanish branch till the time is it being reviewed and merged in develop branch. I hope that should be a good starting point?

@DeeDeeG I have been going through the PR comments, You have explained many things in detail. Reading them will impart a lot of knowledge to me. Thanks for all the explanations & teaching. 🙌

Regarding the process of review and time that may be required, I am more than happy to wait. It great to see volunteers putting in their efforts apart from their daily schedule. Thanks to all the past & present core maintainers for their time. Will be starting off with translation soon.

Cheers, Ashish