translate: support format option to specify html or text

[WarTech9]

Fixes #1573

Adds the 'format' parameter to the translate request if specified by caller.

[googlebot]

Thanks for your pull request. It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

📝 Please visit https://cla.developers.google.com/ to sign.

Once you've signed, please reply here (e.g. I signed it!) and we'll verify. Thanks.

---

• If you've already signed a CLA, it's possible we don't have your GitHub username or you're using a different email address. Check your existing CLA data and verify that your email is set on your git commits.
• If you signed the CLA as a corporation, please let us know the company's name.

[stephenplusplus]

Do you think something like is-html would be reliable?

[WarTech9]

You mean using is-html to test the input? That could work, but what if the input is not html but the caller wants html output, or the other way around? Having an option parameter override covers that case.

Btw, I signed the CLA.

[googlebot]

CLAs look good, thanks!

[stephenplusplus]

but what if the input is not html but the caller wants html output

Are there reasons why someone would want to do that? I assume the API wouldn't do its job as well if the format didn't match the input.

[WarTech9]

I assume the API wouldn't do its job as well if the format didn't match the input.

That is the current behaviour: The API auto detects the source language but doesn't auto detect the format type, it defaults to html if the format parameter is missing, regardless of the actual input format.
https://cloud.google.com/translate/v2/translate-reference#format

So the caller can choose the output format. That is also how the Google Node.js client works as well, by passing a format parameter. Which is why I thought the a parameter should be used here too, as I was coming from that client.
https://github.com/google/google-api-nodejs-client/blob/master/apis/translate/v2.js#L141

I suppose other devs coming from the node client would expect it to work the same way.

[stephenplusplus]

I think this is a case where we can try to out-smart the API. If we can detect that the user's input is HTML or text, then they shouldn't need to override it. However, I'm not certain is-html is going to always be correct for the various snippets of input the user will be giving us. So, I think you were right that we should do both. If the user doesn't provide options.format, can you set it for them?

var query = {
  q: arrify(input),
+ format: options.format || isHtml(query.q[0]) ? 'html' : 'text'
};

[stephenplusplus]

Continued in #1647.