Prep translate docs for repo split. (#5941)

- Move docs from 'docs/translate' into 'translate/docs' and leave symlink.
- Harmonize / DRY 'translate/README.rst' and 'translate/docs/index.rst'.
- Ensure that docs still build from top-level.

Toward #5912.

docs/index.rst

@@ -31,7 +31,7 @@
   storage/index
   tasks/index
   texttospeech/index
-  translate/usage
+  translate/index
   vision/index
   videointelligence/index
   websecurityscanner/index

docs/translate

@@ -0,0 +1 @@
+../translate/docs

translate/README.rst

@@ -1,53 +1,111 @@
 Python Client for Google Cloud Translation
 ==========================================
 
-    Python idiomatic client for `Google Cloud Translation`_
+|pypi| |versions|
 
-.. _Google Cloud Translation: https://cloud.google.com/translate/
+With `Google Cloud Translation`_, you can dynamically translate text between
+thousands of language pairs. The Google Cloud Translation API lets websites
+and programs integrate with Google Cloud Translation programmatically. Google
+Cloud Translation is available as a paid service. See the `Pricing`_ and
+`FAQ`_ pages for details.
 
-|pypi| |versions|
+- `Client Library Documentation`_
+- `Product Documentation`_
 
--  `Documentation`_
 
-.. _Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/translate/usage.html
+.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-translate.svg
+   :target: https://pypi.org/project/google-cloud-translate/
+.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-translate.svg
+   :target: https://pypi.org/project/google-cloud-translate/
+.. _Google Cloud Translation: https://cloud.google.com/translate/
+.. _Pricing: https://cloud.google.com/translate/pricing
+.. _FAQ: https://cloud.google.com/translate/faq
+.. _Client Library Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/translate/usage.html
+.. _Product Documentation: https://cloud.google.com/translate/docs
 
 Quick Start
 -----------
 
-.. code-block:: console
+In order to use this library, you first need to go through the following steps:
 
-    $ pip install --upgrade google-cloud-translate
+1. `Select or create a Cloud Platform project.`_
+2. `Enable billing for your project.`_
+3. `Enable the Google Cloud Datastore API.`_
+4. `Setup Authentication.`_
 
-For more information on setting up your Python development environment,
-such as installing ``pip`` and ``virtualenv`` on your system, please refer
-to `Python Development Environment Setup Guide`_ for Google Cloud Platform.
+.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project
+.. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project
+.. _Enable the Google Cloud Datastore API.:  https://cloud.google.com/datastore
+.. _Setup Authentication.: https://googlecloudplatform.github.io/google-cloud-python/latest/core/auth.html
 
-.. _Python Development Environment Setup Guide: https://cloud.google.com/python/setup
+Installation
+~~~~~~~~~~~~
 
-Authentication
---------------
+Install this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to
+create isolated Python environments. The basic problem it addresses is one of
+dependencies and versions, and indirectly permissions.
 
-With ``google-cloud-python`` we try to make authentication as painless as
-possible. Check out the `Authentication section`_ in our documentation to
-learn more. You may also find the `authentication document`_ shared by all
-the ``google-cloud-*`` libraries to be helpful.
+With `virtualenv`_, it's possible to install this library without needing system
+install permissions, and without clashing with the installed system
+dependencies.
 
-.. _Authentication section: https://google-cloud-python.readthedocs.io/en/latest/core/auth.html
-.. _authentication document: https://github.com/GoogleCloudPlatform/google-cloud-common/tree/master/authentication
+.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/
 
-Using the API
--------------
 
-With the Google Cloud `Translation`_ API (`Translation API docs`_), you can
-dynamically translate text between thousands of language pairs.
+Mac/Linux
+^^^^^^^^^
 
-.. _Translation: https://cloud.google.com/translate/
-.. _Translation API docs: https://cloud.google.com/translate/docs/apis
+.. code-block:: console
 
-See the ``google-cloud-python`` API Translation `Documentation`_ to learn
-how to translate text using this library.
+    pip install virtualenv
+    virtualenv <your-env>
+    source <your-env>/bin/activate
+    <your-env>/bin/pip install google-cloud-datastore
 
-.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-translate.svg
-   :target: https://pypi.org/project/google-cloud-translate/
-.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-translate.svg
-   :target: https://pypi.org/project/google-cloud-translate/
+
+Windows
+^^^^^^^
+
+.. code-block:: console
+
+    pip install virtualenv
+    virtualenv <your-env>
+    <your-env>\Scripts\activate
+    <your-env>\Scripts\pip.exe install google-cloud-datastore
+
+
+Example Usage
+~~~~~~~~~~~~~
+
+.. code-block:: python
+
+     >>> from google.cloud import translate
+     >>> client = translate.Client()
+     >>> client.get_languages()
+     [
+         {
+             'language': 'af',
+             'name': 'Afrikaans',
+         },
+          ...
+     ]
+     >>> client.detect_language(['Me llamo', 'I am'])
+     [
+         {
+             'confidence': 0.25830904,
+             'input': 'Me llamo',
+             'language': 'es',
+         }, {
+             'confidence': 0.17112699,
+             'input': 'I am',
+             'language': 'en',
+         },
+     ]
+     >>> from google.cloud import translate
+     >>> client = translate.Client()
+     >>> client.translate('koszula')
+     {
+         'translatedText': 'shirt',
+         'detectedSourceLanguage': 'pl',
+         'input': 'koszula',
+     }