lib/google/cloud/translate.rb in google-cloud-translate-1.2.1 vs lib/google/cloud/translate.rb in google-cloud-translate-1.2.2

- old
+ new

@@ -34,225 +34,22 @@ # 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. # - # ## Authenticating + # See {file:OVERVIEW.md Translation Overview}. # - # 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 - # [Authentication Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-translate/guides/authentication). - # - # ## Enabling Logging - # - # To enable logging for this library, set the logger for the underlying - # [gRPC](https://github.com/grpc/grpc/tree/master/src/ruby) library. The - # logger that you set may be a Ruby stdlib - # [`Logger`](https://ruby-doc.org/stdlib-2.5.0/libdoc/logger/rdoc/Logger.html) - # as shown below, or a - # [`Google::Cloud::Logging::Logger`](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-logging/latest/google/cloud/logging/logger) - # that will write logs to [Stackdriver - # Logging](https://cloud.google.com/logging/). See - # [grpc/logconfig.rb](https://github.com/grpc/grpc/blob/master/src/ruby/lib/grpc/logconfig.rb) - # and the gRPC - # [spec_helper.rb](https://github.com/grpc/grpc/blob/master/src/ruby/spec/spec_helper.rb) - # for additional information. - # - # Configuring a Ruby stdlib logger: - # - # ```ruby - # require "logger" - # - # module MyLogger - # LOGGER = Logger.new $stderr, level: Logger::WARN - # def logger - # LOGGER - # end - # end - # - # # Define a gRPC module-level logger method before grpc/logconfig.rb loads. - # module GRPC - # extend MyLogger - # end - # ``` - # - # ## Translating texts - # - # Translating text from one language to another is easy (and extremely - # fast.) The only required arguments to - # {Google::Cloud::Translate::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 - # - # 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 - # - # 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::Api#translate}. - # - # ```ruby - # require "google/cloud/translate" - # - # translate = Google::Cloud::Translate.new - # - # 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 - # - # translation = translate.translate "<strong>Hello</strong> world!", - # to: :la - # translation.text #=> "<strong>Salve</strong> mundi!" - # ``` - # - # ## Detecting languages - # - # You can use {Google::Cloud::Translate::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 - # - # detection = translate.detect "chat" - # - # detection.text #=> "chat" - # detection.language #=> "en" - # detection.confidence #=> 0.59922177 - # ``` - # - # You can pass multiple texts to {Google::Cloud::Translate::Api#detect}. - # - # ```ruby - # require "google/cloud/translate" - # - # translate = Google::Cloud::Translate.new - # - # 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::Api#languages} to query the list of supported - # languages. - # - # ```ruby - # require "google/cloud/translate" - # - # translate = Google::Cloud::Translate.new - # - # 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 - # - # 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 retries: 10, timeout: 120 - # ``` - # module Translate ## # 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 [Authentication - # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-translate/guides/authentication). + # 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