More fully document CLI push and pull

[rlundy]

We're running into issues using the push and pull CLI commands: old, revised translations are cropping up where they should've been fixed.

I've searched the documentation for a clear, precise explanation of what push and pull do, and haven't found anything. I've also looked through the API docs, but they're at a much more granular level and don't appear to address the CLI's push and pull.

Request: Please update the documentation to explain exactly what operations push and pull perform. Ideally there would be some small sample cases that demonstrate correct usage. It might even be worth showing a sample case or two with incorrect usage just to help with troubleshooting in cases like ours.

[jablan]

Hi @rlundy what do you consider missing from https://support.phrase.com/hc/en-us/articles/5808300599068-Using-the-CLI-Strings#push-and-pull-0-6?

Under the hood, push and pull rely on API endpoints for creating uploads and downloading locales respectively.

[rlundy]

For starters, it would be helpful to include those links in the CLI push/pull section.

Then, questions I would have would be about conflicts and who wins:

• If there's a new key in the localization file, does it get added to Phrase?
• If there's a new key in Phrase, does it get added to the localization file? (Or can new keys only be created in the localization file?)
• If for a given key there's a conflict in translations between Phrase and the localization file, who wins? Does it depend on whether there's an upload or download?

etc.

In our most recent release we had some regressions, where updated translations disappeared and older translations ended up in our release, so we're trying to understand exactly how the push/pull process works so we can understand what happened there and avoid it next time.