Dakwak::Api

API wrapper in Ruby for dakwak API

dakwak

dakwak is a website translation and localization technology that helps businesses in going global by having up and running translated versions of their website with no technical involvement and no integration.

Translation quality is user-controlled through dakwak's multi-layered translation system offering machine, team, and professional translation options.

Translated versions of the website run initially under a temporary subdomain provided by dakwak till the user configures his DNS and makes those versions run under his own domain name.

Once the translated website is running under your own domain name, translated pages will start being indexed in search engines making your website visible to people searching in their native language.

https://dakwak.com

Installation

Add this line to your application's Gemfile:

gem 'dakwak-api'

And then execute:

$ bundle

Or install it yourself as:

$ gem install dakwak-api

Usage

To start, create a wrapper and pass in your website's API key:

wrapper = Dakwak::Api::Wrapper.new(APIKEY)

If you don't know your website's API key:

  • Login to dakwak
  • Go to Dashboard -> My Website Content -> Settings
  • Click on blue the button "Request API Key"

An email will be sent to the support staff at dakwak and they will contact you with your website’s API Key.

Next, you can use any of these methods on your wrapper object

get_translation

wrapper.get_translation(phrase, lang)

Returns the translation of a given phrase in the given language:

  • It returns the published translation of a given term
  • If no published translation was found, it returns the unpublished translation with the highest level
  • If no unpublished translation was found, return an empty string Example
wrapper.get_translation("hola", "ar")

This says: get me the translation of hola in Arabic, and it will return a hash of the following:

{"apikey"=>"1234567890abcdef", "lang"=>"ar", "phrase"=>"hola", "translation"=>"مرحبا"}

Note: If the phrase has not been translated before, you will get an error. In that case, you can use the translate() method to translate that phrase.

translate

wrapper.translate(phrase, lang, callback_url="")

Returns the translation of given phrases in the given language. If no translation was available for a certain phrase, it will do the following:

  • If you provided a callback URL, it will translate the phrase & send the translation in a POST request to the callback URL
  • If no callback URL was provided, it will still translate the phrase, but you have to send a request again to get the translation

Example

wrapper.translate(["hello", "welcome"], "ar")

This says: get me the translation of 'hello' and 'welcome' in Arabic, and it will return a hash of the following:

{"apikey"=>"1234567890abcdef", "lang"=>"ar", "translation"=>{"hello"=>"مرحبا", "welcome"=>"ترحيب"}}

create_translator

wrapper.create_translator(email,username,password,grant_admin)

returns the created translator in json format, it will do the following:

  • If no username or password was provided, it will still create translator with a generated name and password
  • if you pass grant_admin 0 then it will not grant translator admin privileges, if you pass 1 then it will grant translator admin privileges

Example

wrapper.create_translator("[email protected]","example","password_example",1)

This says: create me a translator with email '[email protected]' , username 'example',password 'password_example' and '1' to grant translator admin privileges, it will return a hash of the following:

{"apikey"=>"1234567890abcdef", "email"=>"[email protected]", "username"=>"example",password=>"password_example"}

wrapper.search(phrase, lang)

Returns the phrases that match your query in the translated and the original versions of your website, along with the pages where these phrases were found.

Example

wrapper.search("hola", "es")

This says: search through my Spanish website and original website for 'hola', and return URLs of pages where this phrase was found.

{"apikey"=>"1234567890abcdef", "lang"=>"ar", "phrase"=>"welcome", "results"=>[
  {"source_text": "hello world","translated_text": "hola mundo","page_urls": ["/page1", "/page2"]}, 
  {"source_text": "hi","translated_text": "hola","page_urls": ["/page3", "/page4"]
}]

index_pages

wrapper.index_pages(pages)

This method basically indexes the pages you request. By indexing, we mean send a GET request to that page & therefor translating it.

Example

wrapper.index_pages(["/page1", "/page2"])

Note: Indexing will happen as a background job, so it will not show any error messages if the indexing fails (returns 404, etc)

Notes:

  • These methods assumes you have translated your website to the language of the phrase and the language requested. Otherwise you will get an error.
  • the "lang" field of these methods accepts the shortcut version of the language, which are:

Valid values for 'lang' field

Language Shortcut Language Shortcut Language Shortcut
Afrikaans af Greek el Romanian ro
Albanian sq Hebrew iw Russian ru
Arabic ar Hindi hi Serbian sr
Belarusian be Hungarian hu Slovak sk
Bulgarian bg Icelandic is Slovenian sl
Catalan ca Indonesian id Spanish es
Chinese (Simplified) zh-CN Irish ga Swahili sw
Croatian hr Italian it Swedish sv
Czech cs Japanese ja Thai th
Danish da Korean ko Turkish tr
Dutch nl Latvian lv Ukrainian uk
English en Lithuanian lt Vietnamese vi
Estonian et Macedonian mk Welsh cy
Filipino tl Malay ms Yiddish yi
Finnish fi Maltese mt Urdu ur
French fr Persian fa Chinese (Traditional) zh-TW
Galician gl Polish pl French (Canada) fr-CA
German de Portuguese (Europe) pt-PT Spanish (Latin America) es-LA
Portuguese (Brazil) pt-BR

Error Messages

Here's a list of error messages & more details about them:

  • invalid apikey: your apikey is invalid, check you've copied and pasted it correctly.
  • website is locked: one possible reason for this is that your trial was over and you haven't upgraded yet.
  • lang is not valid or supported: the language you requested is not supported by dakwak.com or does not exist. Make sure to choose the correct language shortcut from the table above
  • lang is not included in your plan: The language you chose is not included in your plan, please choose another language
  • phrase was not found: the phrase was not found in the database, you can request a translation by using the translate() method

Support

If you have questions or any inquries, please email [email protected]