Tolq::Api

The Tolq Api gem wraps our api, making it a lot easier to integrate it with your Ruby application.

Installation

Add this line to your application's Gemfile:

gem 'tolq-api'

And then execute:

$ bundle

Or install it yourself as:

$ gem install tolq-api

Usage

For an overview of how our api works, see the documentation.

First, you need to create a a client.

client = Tolq::Api::Client.new(ENV['TOLQAPIKEY'], ENV['TOLQAPISECRET'])

Before making any translation requests, make sure you have set up your billing information correctly.

You can directly create and order a translation request:

response = client.translation_requests.create(
    "request" => {
        "a.key" => {
            "text" => "A sentence to translate"
        }
    },
    "source_language_code" => "en",
    "target_language_code" => "nl",
    "quality" => "standard",
    "options" => {
        "name" => "My translation request",
        "callback_url" => "https://mysite.com/translations_finished"
    }

)

response.class # Tolq::Api::Response
response.body # A tolq response as per the documentation. This JSON and can be parsed using your favourite json parser

When present, Tolq will make a callback to the callback url when the translations have been fully finished.

You can also create a quote, these will not be ordered directly and need your confirmation.

response = client.translation_requests.quote(
    "request" => {
        "a.key" => {
            "text" => "A sentence to translate"
        }
    },
    "source_language_code" => "en",
    "target_language_code" => "nl",
    "quality" => "standard",
    "options" => {
        "name" => "My translation request",
        "callback_url" => "https://mysite.com/translations_finished"
    }

)

response.class # Tolq::Api::Response
response.body # A tolq response as per the documentation. This JSON and can be parsed using your favourite json parser

After creating the quote, you can order it:

client.translation_request.order(response.id)

If you do not have a callback url or are just interested in the status, you can request the status and/or translations as follows:

response = client.translation_requests.show(<id>)
response.class # Tolq::Api::Response
response.body # A tolq response as per the documentation. This JSON and can be parsed using your favourite json parser

You can verify a callback HMAC signature by calling client.valid_signature?, this can be used to verify the authenticity of a callback.

For more details on on the library please refer to the gem documentation. For more details on possible values see the api documentation.

Development

TODO

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/tolq-api. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.