Translation API Documentation

Description:

This API allows you to seamlessly translate text from one language to another. To use this API, you need to authenticate with an API token. Below, you'll find comprehensive guidance on how to use this API effectively.

Endpoint: https://kafkai.io/api/v1.0/translator-api/

Authentication

To access the Translation API, you need to include your API token in the headers of your requests.

Headers:

• Authorization (string): Set this header to include your API token in the following format: Token <your_api_token>.

Example:

curl -X POST "https://kafkai.io/api/v1.0/translator-api/ -d "source_text=Hello, how are you?" 
    -d "output_lang=FR" -H "Authorization: Token <your-api-key>"

Input and Output

POST Method (Create Translation)

Input: To initiate a translation, send a POST request with these parameters:

• source_text (string): The text you intend to translate.
• output_lang (string): The language code of your desired translation (e.g., "EN" for English).
• formal (boolean, optional): Set this to true for a formal translation (supported for specific languages).

Output: Upon a successful translation request, the API will respond with essential details:

• source_lang (string): The language of your source text.
• translated_lang (string): The language of your translated text.
• translated_text (string): The translated text.
• source_text (string): The original text you provided.

Notes:

• The POST method is used to create a new translation.
• You provide input parameters like source_text and output_lang.
• The API returns a response containing details of the translation.

GET Method (Retrieve Translation)

Input: To access an existing translation, submit a GET request with the uid parameter specifying the unique ID of the translation you want to retrieve.

Output: The API will furnish the following information:

• uid (string): The unique ID of the translation.
• time (timestamp): The timestamp when the translation was created.
• formal (boolean): Indicates whether the translation is formal.
• source_text (string): The source text.
• source_lang (string): The language of the source text.
• output_text (string): The translated text.
• output_lang (string): The language of the translated text.

Notes:

• The GET method is used to retrieve an existing translation.
• You provide the uid parameter to specify which translation to retrieve.
• The API responds with the details of the requested translation.

Practical Examples

Creating a New Translation (POST Method)

Scenario 1: Translate "Hello, how are you?" from English to French.

Using CURL:

curl -X POST "https://kafkai.io/api/v1.0/translator-api/ -d "source_text=Hello, how are you?" 
-d "output_lang=FR" -H "Authorization: Token <your-api-key>"

Expected Result (JSON Response):

{
    "source_lang": "en",
    "translated_lang": "fr",
    "translated_text": "Bonjour, comment ça va ?",
    "source_text": "Hello, how are you?"
}

Using Python (requests library):

import requests

url = 'https://kafkai.io/api/v1.0/translator-api/'
data = {
    'source_text': 'Hello, how are you?',
    'output_lang': 'FR'
}
headers = {
    'Authorization': 'Token <your-api-key>'
}
response = requests.post(url, data=data, headers=headers)
print(response.json())

Notes:

• We are translating a specific text from English to French.
• The CURL command sends a POST request to create the translation with the authorization token included in the headers.
• The Python script demonstrates the same with the token in the headers.

Scenario 2: Translate "Good morning" from English to Spanish.

Using CURL:

curl -X POST https://kafkai.io/api/v1.0/translator-api/ -d "source_text=Good morning" -d "output_lang=ES" -H "Authorization: Token <your-api-key>"

Expected Result (JSON Response):

{
    "source_lang": "en",
    "translated_lang": "es",
    "translated_text": "Buenos días",
    "source_text": "Good morning"
}

Using Python (requests library):

import requests

url = 'https://kafkai.io/api/v1.0/translator-api/'
data = {
    'source_text': 'Good morning',
    'output_lang': 'ES'
}
headers = {
    'Authorization': 'Token <your_api_key>'
}
response = requests.post(url, data=data, headers=headers)
print(response.json())

Notes:

• In this scenario, we translate a different text from English to Spanish.
• The CURL command creates a new translation request with the authorization token included.
• The Python script demonstrates the same with the token in the headers.

Retrieving an Existing Translation (GET Method)

Scenario: Retrieve the translation result for a previous request with a known uid.

Using CURL:

curl https://kafkai.io/api/v1.0/translator-api/{uid}/ -H "Authorization: Token <your_api_key>"

Expected Result (JSON Response):

{
    "uid": "{uid}",
    "time": "2023-09-28T12:00:00Z",
    "formal": false,
    "source_text": "Good morning",
    "source_lang": "en",
    "output_text": "Buenos días",
    "output_lang": "es"
}

Using Python (requests library):

import requests

url = 'https://kafkai.io/api/v1.0/translator-api/{uid}/'
headers = {
    'Authorization': 'Token <your_api_key>'
}
response = requests.get(url, headers=headers)
print(response.json())

Notes:

• In this scenario, we retrieve the translation result by specifying the uid parameter with the authorization token included.
• The CURL command sends a GET request to access the translation.
• The Python script demonstrates the same with the token in the headers.

---