google-cloud-translate 2.3.0 → 3.0.0

data/OVERVIEW.md

@@ -1,390 +0,0 @@
-# Google Cloud Translation API
-
-[Google Cloud Translation API](https://cloud.google.com/translation/)
-provides a simple, programmatic interface for translating an arbitrary
-string into any supported language. It is highly responsive, so websites
-and applications can integrate with Translation API for fast, dynamic
-translation of source text. Language detection is also available in cases
-where the source language is unknown.
-
-Translation API supports more than one hundred different languages, from
-Afrikaans to Zulu. Used in combination, this enables translation between
-thousands of language pairs. Also, you can send in HTML and receive HTML
-with translated text back. You don't need to extract your source text or
-reassemble the translated content.
-
-The google-cloud-translate 2.0 gem contains a generated v3 client and a legacy hand-written v2 client.
-To use the legacy v2 client, call {Google::Cloud::Translate.new} and specify `version: :v2`.
-See [Migrating to Translation v3](https://cloud.google.com/translate/docs/migrate-to-v3) for details regarding differences between v2 and v3.
-
-## Authenticating
-
-Like other Cloud Platform services, Google Cloud Translation API supports
-authentication using a project ID and OAuth 2.0 credentials. In addition,
-it supports authentication using a public API access key. (If both the API
-key and the project and OAuth 2.0 credentials are provided, the API key
-will be used.) Instructions and configuration options are covered in the
-{file:AUTHENTICATION.md Authentication Guide}.
-
-## Using the v3 client
-
-The Cloud Translation API v3 includes several new features and updates:
-
-* Glossaries - Create a custom dictionary to correctly and consistently translate terms that are customer-specific.
-* Batch requests - Make an asynchronous request to translate large amounts of text.
-* AutoML models - Cloud Translation adds support for translating text with custom models that you create using AutoML Translation.
-* Labels - The Cloud Translation API supports adding user-defined labels (key-value pairs) to requests.
-
-### Translating texts
-
-Cloud Translation v3 introduces support for translating text using custom AutoML Translation models, and for creating glossaries to ensure that the Cloud Translation API translates a customer's domain-specific terminology correctly.
-
-Performing a default translation:
-
-```ruby
-require "google/cloud/translate"
-
-client = Google::Cloud::Translate.new
-
-project_id = "my-project-id"
-location_id = "us-central1"
-
-# The content to translate in string format
-contents = ["Hello, world!"]
-# Required. The BCP-47 language code to use for translation.
-target_language = "fr"
-parent = client.class.location_path project_id, location_id
-
-response = client.translate_text contents, target_language, parent
-
-# Display the translation for each input text provided
-response.translations.each do |translation|
-  puts "Translated text: #{translation.translated_text}"
-end
-```
-
-To use AutoML custom models you enable the [AutoML API](automl.googleapis.com) for your project before translating as follows:
-
-```ruby
-require "google/cloud/translate"
-
-client = Google::Cloud::Translate.new
-
-project_id = "my-project-id"
-location_id = "us-central1"
-model_id = "my-automl-model-id"
-
-# The `model` type requested for this translation.
-model = "projects/#{project_id}/locations/#{location_id}/models/#{model_id}"
-# The content to translate in string format
-contents = ["Hello, world!"]
-# Required. The BCP-47 language code to use for translation.
-target_language = "fr"
-# Optional. The BCP-47 language code of the input text.
-source_language = "en"
-# Optional. Can be "text/plain" or "text/html".
-mime_type = "text/plain"
-parent = client.class.location_path project_id, location_id
-
-response = client.translate_text contents, target_language, parent,
-  source_language_code: source_language, model: model, mime_type: mime_type
-
-# Display the translation for each input text provided
-response.translations.each do |translation|
-  puts "Translated text: #{translation.translated_text}"
-end
-```
-
-To use a glossary you need to create a Google Cloud Storage bucket and grant your service account access to it before translating as follows:
-
-```ruby
-require "google/cloud/translate"
-
-client = Google::Cloud::Translate.new
-
-project_id = "my-project-id"
-location_id = "us-central1"
-glossary_id = "my-glossary-id"
-
-# The content to translate in string format
-contents = ["Hello, world!"]
-# Required. The BCP-47 language code to use for translation.
-target_language = "fr"
-# Optional. The BCP-47 language code of the input text.
-source_language = "en"
-glossary_config = {
-  # Specifies the glossary used for this translation.
-  glossary: client.class.glossary_path(project_id, location_id, glossary_id)
-}
-# Optional. Can be "text/plain" or "text/html".
-mime_type = "text/plain"
-parent = client.class.location_path project_id, location_id
-
-response = client.translate_text contents, target_language, parent,
-  source_language_code: source_language, glossary_config: glossary_config, mime_type: mime_type
-
-# Display the translation for each input text provided
-response.translations.each do |translation|
-  puts "Translated text: #{translation.translated_text}"
-end
-```
-
-### Batch translating texts
-
-Batch translation allows you to translate large amounts of text (with a limit of 1,000 files per batch), and to up to 10 different target languages.
-Batch translation also supports AutoML models and glossaries.
-To make batch requests you need to create a Google Cloud Storage bucket and grant your service account access to it before translating as follows:
-
-```ruby
-require "google/cloud/translate"
-
-client = Google::Cloud::Translate.new
-
-input_uri = "gs://cloud-samples-data/text.txt"
-output_uri = "gs://my-bucket-id/path_to_store_results/"
-project_id = "my-project-id"
-location_id = "us-central1"
-source_lang = "en"
-target_lang = "ja"
-
-input_config = {
-  gcs_source: {
-    input_uri: input_uri
-  },
-  # Optional. Can be "text/plain" or "text/html".
-  mime_type: "text/plain"
-}
-output_config = {
-  gcs_destination: {
-    output_uri_prefix: output_uri
-  }
-}
-parent = client.class.location_path project_id, location_id
-
-operation = client.batch_translate_text \
-  parent, source_lang, [target_lang], [input_config], output_config
-
-# Wait until the long running operation is done
-operation.wait_until_done!
-
-response = operation.response
-
-puts "Total Characters: #{response.total_characters}"
-puts "Translated Characters: #{response.translated_characters}"
-```
-
-### Detecting languages
-
-You can detect the language of a text string:
-
-```ruby
-require "google/cloud/translate"
-
-client = Google::Cloud::Translate.new
-
-project_id = "my-project-id"
-location_id = "us-central1"
-# The text string for performing language detection
-content = "Hello, world!"
-# Optional. Can be "text/plain" or "text/html".
-mime_type = "text/plain"
-
-parent = client.class.location_path project_id, location_id
-
-response = client.detect_language parent, content: content, mime_type: mime_type
-
-# Display list of detected languages sorted by detection confidence.
-# The most probable language is first.
-response.languages.each do |language|
-  # The language detected
-  puts "Language Code: #{language.language_code}"
-  # Confidence of detection result for this language
-  puts "Confidence: #{language.confidence}"
-end
-```
-
-### Listing supported languages
-
-You can discover the [supported languages](https://cloud.google.com/translate/docs/languages) of the v3 API:
-
-```ruby
-require "google/cloud/translate"
-
-client = Google::Cloud::Translate.new
-
-project_id = "my-project-id"
-location_id = "us-central1"
-
-parent = client.class.location_path project_id, location_id
-
-response = client.get_supported_languages parent
-
-# List language codes of supported languages
-response.languages.each do |language|
-  puts "Language Code: #{language.language_code}"
-end
-```
-
-## Using the legacy v2 client
-
-### Translating texts
-
-Translating text from one language to another is easy (and extremely
-fast.) The only required arguments to
-{Google::Cloud::Translate::V2::Api#translate} are a string and the [ISO
-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) code of the
-language to which you wish to translate.
-
-```ruby
-require "google/cloud/translate"
-
-translate = Google::Cloud::Translate.new version: :v2
-
-translation = translate.translate "Hello world!", to: "la"
-
-puts translation #=> Salve mundi!
-
-translation.from #=> "en"
-translation.origin #=> "Hello world!"
-translation.to #=> "la"
-translation.text #=> "Salve mundi!"
-```
-
-You may want to use the `from` option to specify the language of the
-source text, as the following example illustrates. (Single words do not
-give Translation API much to work with.)
-
-```ruby
-require "google/cloud/translate"
-
-translate = Google::Cloud::Translate.new version: :v2
-
-translation = translate.translate "chat", to: "en"
-
-translation.detected? #=> true
-translation.from #=> "en"
-translation.text #=> "chat"
-
-translation = translate.translate "chat", from: "fr", to: "en"
-
-translation.detected? #=> false
-translation.from #=> "fr"
-translation.text #=> "cat"
-```
-
-You can pass multiple texts to {Google::Cloud::Translate::V2::Api#translate}.
-
-```ruby
-require "google/cloud/translate"
-
-translate = Google::Cloud::Translate.new version: :v2
-
-translations = translate.translate "chien", "chat", from: "fr", to: "en"
-
-translations.size #=> 2
-translations[0].origin #=> "chien"
-translations[0].text #=> "dog"
-translations[1].origin #=> "chat"
-translations[1].text #=> "cat"
-```
-
-By default, any HTML in your source text will be preserved.
-
-```ruby
-require "google/cloud/translate"
-
-translate = Google::Cloud::Translate.new version: :v2
-
-translation = translate.translate "<strong>Hello</strong> world!",
-                                  to: :la
-translation.text #=> "<strong>Salve</strong> mundi!"
-```
-
-### Detecting languages
-
-You can use {Google::Cloud::Translate::V2::Api#detect} to see which language
-the Translation API ranks as the most likely source language for a text.
-The `confidence` score is a float value between `0` and `1`.
-
-```ruby
-require "google/cloud/translate"
-
-translate = Google::Cloud::Translate.new version: :v2
-
-detection = translate.detect "chat"
-
-detection.text #=> "chat"
-detection.language #=> "en"
-detection.confidence #=> 0.59922177
-```
-
-You can pass multiple texts to {Google::Cloud::Translate::V2::Api#detect}.
-
-```ruby
-require "google/cloud/translate"
-
-translate = Google::Cloud::Translate.new version: :v2
-
-detections = translate.detect "chien", "chat"
-
-detections.size #=> 2
-detections[0].text #=> "chien"
-detections[0].language #=> "fr"
-detections[0].confidence #=> 0.7109375
-detections[1].text #=> "chat"
-detections[1].language #=> "en"
-detections[1].confidence #=> 0.59922177
-```
-
-### Listing supported languages
-
-Translation API adds new languages frequently. You can use
-{Google::Cloud::Translate::V2::Api#languages} to query the list of supported
-languages.
-
-```ruby
-require "google/cloud/translate"
-
-translate = Google::Cloud::Translate.new version: :v2
-
-languages = translate.languages
-
-languages.size #=> 104
-languages[0].code #=> "af"
-languages[0].name #=> nil
-```
-
-To receive the names of the supported languages, as well as their [ISO
-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) codes,
-provide the code for the language in which you wish to receive the names.
-
-```ruby
-require "google/cloud/translate"
-
-translate = Google::Cloud::Translate.new version: :v2
-
-languages = translate.languages "en"
-
-languages.size #=> 104
-languages[0].code #=> "af"
-languages[0].name #=> "Afrikaans"
-```
-
-### Configuring retries and timeout
-
-You can configure how many times API requests may be automatically
-retried. When an API request fails, the response will be inspected to see
-if the request meets criteria indicating that it may succeed on retry,
-such as `500` and `503` status codes or a specific internal error code
-such as `rateLimitExceeded`. If it meets the criteria, the request will be
-retried after a delay. If another error occurs, the delay will be
-increased before a subsequent attempt, until the `retries` limit is
-reached.
-
-You can also set the request `timeout` value in seconds.
-
-```ruby
-require "google/cloud/translate"
-
-translate = Google::Cloud::Translate.new version: :v2, retries: 10, timeout: 120
-```

data/TROUBLESHOOTING.md

@@ -1,37 +0,0 @@
-# Troubleshooting
-
-## Where can I get more help?
-
-### Ask the Community
-
-If you have a question about how to use a Google Cloud client library in your
-project or are stuck in the Developer's console and don't know where to turn,
-it's possible your questions have already been addressed by the community.
-
-First, check out the appropriate tags on StackOverflow:
-  - [`google-cloud-platform+ruby+translate`][so-ruby]
-
-Next, try searching through the issues on GitHub:
-
-  - [`api:translate` issues][gh-search-ruby]
-
-Still nothing?
-
-### Ask the Developers
-
-If you're experiencing a bug with the code, or have an idea for how it can be
-improved, *please* create a new issue on GitHub so we can talk about it.
-
-  - [New issue][gh-ruby]
-
-Or, you can ask questions on the [Google Cloud Platform Slack][slack-ruby]. You
-can use the "ruby" channel for general Ruby questions, or use the
-"google-cloud-ruby" channel if you have questions about this gem in particular.
-
-[so-ruby]: http://stackoverflow.com/questions/tagged/google-cloud-platform+ruby+translate
-
-[gh-search-ruby]: https://github.com/googlecloudplatform/google-cloud-ruby/issues?q=label%3A%22api%3A+translate%22
-
-[gh-ruby]: https://github.com/googlecloudplatform/google-cloud-ruby/issues/new
-
-[slack-ruby]: https://gcp-slack.appspot.com/

data/lib/google/cloud/translate/v2.rb

@@ -1,169 +0,0 @@
-# Copyright 2016 Google LLC
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     https://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-
-require "google-cloud-translate"
-require "google/cloud/translate/v2/api"
-require "google/cloud/config"
-require "google/cloud/env"
-
-module Google
-  module Cloud
-    module Translate
-      ##
-      # # Google Cloud Translation API
-      #
-      # [Google Cloud Translation API](https://cloud.google.com/translation/)
-      # provides a simple, programmatic interface for translating an arbitrary
-      # string into any supported language. It is highly responsive, so websites
-      # and applications can integrate with Translation API for fast, dynamic
-      # translation of source text. Language detection is also available in cases
-      # where the source language is unknown.
-      #
-      # Translation API supports more than one hundred different languages, from
-      # Afrikaans to Zulu. Used in combination, this enables translation between
-      # thousands of language pairs. Also, you can send in HTML and receive HTML
-      # with translated text back. You don't need to extract your source text or
-      # reassemble the translated content.
-      #
-      # See {file:OVERVIEW.md Translation Overview}.
-      #
-      module V2
-        ##
-        # Creates a new object for connecting to Cloud Translation API. Each call creates a new connection.
-        #
-        # Like other Cloud Platform services, Google Cloud Translation API supports authentication using a project ID
-        # and OAuth 2.0 credentials. In addition, it supports authentication using a public API access key. (If both the
-        # API key and the project and OAuth 2.0 credentials are provided, the API key will be used.) Instructions and
-        # configuration options are covered in the {file:AUTHENTICATION.md Authentication Guide}.
-        #
-        # @param [String] project_id Project identifier for the Cloud Translation service you are connecting to. If not
-        #   present, the default project for the credentials is used.
-        # @param [String, Hash, Google::Auth::Credentials] credentials The path to the keyfile as a String, the contents
-        #   of the keyfile as a Hash, or a Google::Auth::Credentials object. (See {Translate::V2::Credentials})
-        # @param [String] key a public API access key (not an OAuth 2.0 token)
-        # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the set of resources and operations that
-        #   the connection can access. See [Using OAuth 2.0 to Access Google
-        #   APIs](https://developers.google.com/identity/protocols/OAuth2).
-        #
-        #   The default scope is:
-        #
-        #   * `https://www.googleapis.com/auth/cloud-platform`
-        # @param [Integer] retries Number of times to retry requests on server error. The default value is `3`.
-        #   Optional.
-        # @param [Integer] timeout Default timeout to use in requests. Optional.
-        # @param [String] endpoint Override of the endpoint host name. Optional. If the param is nil, uses the default
-        #   endpoint.
-        #
-        # @return [Google::Cloud::Translate::V2::Api]
-        #
-        # @example
-        #   require "google/cloud/translate/v2"
-        #
-        #   translate = Google::Cloud::Translate::V2.new(
-        #     version: :v2,
-        #     project_id: "my-todo-project",
-        #     credentials: "/path/to/keyfile.json"
-        #   )
-        #
-        #   translation = translate.translate "Hello world!", to: "la"
-        #   translation.text #=> "Salve mundi!"
-        #
-        # @example Using API Key.
-        #   require "google/cloud/translate/v2"
-        #
-        #   translate = Google::Cloud::Translate::V2.new(
-        #     key: "api-key-abc123XYZ789"
-        #   )
-        #
-        #   translation = translate.translate "Hello world!", to: "la"
-        #   translation.text #=> "Salve mundi!"
-        #
-        # @example Using API Key from the environment variable.
-        #   require "google/cloud/translate/v2"
-        #
-        #   ENV["TRANSLATE_KEY"] = "api-key-abc123XYZ789"
-        #
-        #   translate = Google::Cloud::Translate::V2.new
-        #
-        #   translation = translate.translate "Hello world!", to: "la"
-        #   translation.text #=> "Salve mundi!"
-        #
-        def self.new project_id: nil, credentials: nil, key: nil, scope: nil, retries: nil, timeout: nil, endpoint: nil
-          project_id ||= default_project_id
-          key        ||= Google::Cloud.configure.translate.key
-          retries    ||= Google::Cloud.configure.translate.retries
-          timeout    ||= Google::Cloud.configure.translate.timeout
-          endpoint   ||= Google::Cloud.configure.translate.endpoint
-
-          if key
-            return Google::Cloud::Translate::V2::Api.new(
-              Google::Cloud::Translate::V2::Service.new(
-                project_id.to_s, nil, retries: retries, timeout: timeout, key: key, host: endpoint
-              )
-            )
-          end
-
-          scope       ||= Google::Cloud.configure.translate.scope
-          credentials ||= default_credentials scope: scope
-
-          unless credentials.is_a? Google::Auth::Credentials
-            credentials = Google::Cloud::Translate::V2::Credentials.new credentials, scope: scope
-          end
-
-          project_id = resolve_project_id project_id, credentials
-          raise ArgumentError, "project_id is missing" if project_id.empty?
-
-          Google::Cloud::Translate::V2::Api.new(
-            Google::Cloud::Translate::V2::Service.new(
-              project_id, credentials, retries: retries, timeout: timeout, host: endpoint
-            )
-          )
-        end
-
-        ##
-        # @private Default project.
-        def self.default_project_id
-          Google::Cloud.configure.translate.project_id ||
-            Google::Cloud.configure.project_id ||
-            Google::Cloud.env.project_id
-        end
-
-        ##
-        # @private Default credentials.
-        def self.default_credentials scope: nil
-          Google::Cloud.configure.translate.credentials ||
-            Google::Cloud.configure.credentials ||
-            Google::Cloud::Translate::V2::Credentials.default(scope: scope)
-        end
-
-        ##
-        # @private Default configuration.
-        def self.default_config
-          Google::Cloud.configure
-        end
-
-        ##
-        # @private Resolve project.
-        def self.resolve_project_id project_id, credentials
-          # Always cast to a string
-          return project_id.to_s unless credentials.respond_to? :project_id
-
-          # Always cast to a string
-          project_id || credentials.project_id.to_s
-        end
-      end
-    end
-  end
-end