Transliterate API : A Hands-on Guide

🔗 Overview

This tutorial demonstrates how to use the Transliteration API to convert text from one script to another while preserving pronunciation. It supports multiple Indic languages and offers customizable numeral formatting.

1. Installation

Before you begin, ensure you have the necessary Python libraries installed. Run the following commands to install the required packages:

1
!pip install -Uqq sarvamai

Import Required Libraries

First, let’s import all the necessary libraries.

1
from sarvamai import SarvamAI

2. Authentication

To use the API, you need an API subscription key. Follow these steps to set up your API key:

1. Obtain your API key: If you don’t have an API key, sign up on the Sarvam AI Dashboard to get one.
2. Replace the placeholder key: In the code below, replace “YOUR_SARVAM_AI_API_KEY” with your actual API key.

1
SARVAM_API_KEY = "YOUR_SARVAM_API_KEY"

3. Understanding the Parameters

🔹 The API takes several key parameters:

✔ input – The text to be transliterated.
✔ source_language_code – Language of the input text.
✔ target_language_code – Desired transliteration output language.
✔ numerals_format – Choose between international (0-9) or native (१-९) numbers.
✔ spoken_form – Whether to convert text into a natural spoken format.
✔ spoken_form_numerals_language – Choose whether numbers should be spoken in English or native language.

🚫 Note: Transliteration between Indic languages (e.g., Hindi → Bengali) is not supported.

4. Basic Usage

4.1: Read the Document

We have two sample documents under the data folder:

• Download sample1.txt
• Download sample2.txt

1
def read_file(file_path, lang_name):
2
    try:
3
        with open(file_path, "r", encoding="utf-8") as file:
4
            # Read the first 5 lines
5
            lines = [next(file) for _ in range(5)]
6
            print(f"=== {lang_name} Text (First Few Lines) ===")
7
            print("".join(lines))  # Print first few lines
8
9
            # Read the remaining content
10
            remaining_text = file.read()
11
12
            # Combine all text
13
            full_doc = "".join(lines) + remaining_text
14
15
            # Count total characters
16
            total_chars = len(full_doc)
17
            print(f"\nTotal number of characters in {lang_name} file:", total_chars)
18
19
            return full_doc
20
    except FileNotFoundError:
21
        print(f"Error: {file_path} not found.")
22
        return None
23
    except Exception as e:
24
        print(f"An error occurred while reading {file_path}: {e}")
25
        return None

1
# Read English and Hindi documents
2
english_doc = read_file("data/sample1.txt", "English")
3
hindi_doc = read_file("data/sample2.txt", "Hindi")

4.2: Split the text into chunks of at most 1000 characters

Since the API has a restriction of 1000 characters per request, we need to split the text accordingly.

1
def chunk_text(text, max_length=1000):
2
    """Splits text into chunks of at most max_length characters while preserving word boundaries."""
3
    chunks = []
4
5
    while len(text) > max_length:
6
        split_index = text.rfind(" ", 0, max_length)  # Find the last space within limit
7
        if split_index == -1:
8
            split_index = max_length  # No space found, force split at max_length
9
10
        chunks.append(text[:split_index].strip())  # Trim spaces before adding
11
        text = text[split_index:].lstrip()  # Remove leading spaces for the next chunk
12
13
    if text:
14
        chunks.append(text.strip())  # Add the last chunk
15
16
    return chunks

1
# Split the text
2
english_text_chunks = chunk_text(english_doc)
3
4
# Display chunk info
5
print(f"Total Chunks: {len(english_text_chunks)}")
6
for i, chunk in enumerate(
7
    english_text_chunks[:3], 1
8
):  # Show only first 3 chunks for preview
9
    print(f"\n=== Chunk {i} (Length: {len(chunk)}) ===\n{chunk}")

1
# Split the text
2
hindi_text_chunks = chunk_text(english_doc)
3
4
# Display chunk info
5
print(f"Total Chunks: {len(hindi_text_chunks)}")
6
for i, chunk in enumerate(
7
    hindi_text_chunks[:3], 1
8
):  # Show only first 3 chunks for preview
9
    print(f"\n=== Chunk {i} (Length: {len(chunk)}) ===\n{chunk}")

4.3: Setting up the API Endpoint

1
client = SarvamAI(api_subscription_key=SARVAM_API_KEY)

1
# Send requests for each chunk
2
translated_texts = []
3
for idx, chunk in enumerate(hindi_text_chunks):
4
    response = client.text.transliterate(
5
        input=chunk,
6
        source_language_code="hi-IN",
7
        target_language_code="hi-IN",
8
        spoken_form=True,
9
        numerals_format="international",
10
    )
11
12
    translated_text = response.transliterated_text
13
    translated_texts.append(translated_text)
14
15
# Combine all translated chunks
16
final_translation = "\n".join(translated_texts)
17
print("\n=== Final Translated Text ===")
18
print(final_translation)

5. Experimenting with Different Options

We currently have three different transliteration models:

5.1 Romanization (Indic → Latin Script)

• Converts Indic scripts to Roman script (English alphabet).
• Example: मैं ऑफिस जा रहा हूँ → main office ja raha hun
• Parameters:
  • source_language_code = "hi-IN"
  • target_language_code = "en-IN"

1
response = client.text.transliterate(
2
    input="मैं ऑफिस जा रहा हूँ",
3
    source_language_code="hi-IN",
4
    target_language_code="en-IN",
5
    spoken_form=True,
6
)
7
8
transliterated_text = response.transliterated_text
9
print(f"Romanized Text: {transliterated_text}")

Romanized Text: Main office ja raha hun

5.2 Conversion to Indic Scripts

• Converts text into an Indic script from various sources:

  • Code-mixed text

    • Example: मैं office जा रहा हूँ → मैं ऑफिस जा रहा हूँ
    • Parameters:
      • source_language_code = "hi-IN"
      • target_language_code = "hi-IN"

  • Romanized text

    • Example: main office ja raha hun → मैं ऑफिस जा रहा हूँ
    • Parameters:
      • source_language_code = "hi-IN"
      • target_language_code = "hi-IN"

  • English text

    • Example: I am going to office → आइ ऍम गोइंग टू ऑफिस
    • Parameters:
      • source_language_code = "en-IN"
      • target_language_code = "hi-IN"

1
response = client.text.transliterate(
2
    input="main office ja raha hun",
3
    source_language_code="hi-IN",
4
    target_language_code="hi-IN",
5
    spoken_form=True,
6
)
7
8
transliterated_text = response.transliterated_text
9
print(f"Transliterated Text: {transliterated_text}")

Transliterated Text: मैं ऑफिस जा रहा हूँ

5.3 Spoken Indic Form

• Converts written text into a more natural spoken form.
• Example: मुझे कल 9:30am को appointment है → मुझे कल सुबह साढ़े नौ बजे अपॉइंटमेंट है

1
response = client.text.transliterate(
2
    input="मुझे कल 9:30am को appointment है",
3
    source_language_code="hi-IN",
4
    target_language_code="hi-IN",
5
    spoken_form=True,
6
)
7
8
transliterated_text = response.transliterated_text
9
print(f"Spoken Text: {transliterated_text}")

Spoken Text: मुझे कल सुबह साढ़े नौ बजे अपॉइंटमेंट है

6. Advanced Features

• numerals_format – Choose between international (0-9) or native (१-९) numbers.
• spoken_form_numerals_language – Choose whether numbers should be spoken in English or the native language.

Numerals Format

numerals_format is an optional parameter with two options:

• international (default): Uses regular numerals (0-9).
• native: Uses language-specific native numerals.

Example:

• If international format is selected → मेरा phone number है: 9840950950.
• If native format is selected → मेरा phone number है: ९८४०९५०९५०.

1
response = client.text.transliterate(
2
    input="मुझे कल 9:30am को appointment है",
3
    source_language_code="hi-IN",
4
    target_language_code="hi-IN",
5
    spoken_form=True,
6
    numerals_format="native",
7
)
8
9
transliterated_text = response.transliterated_text
10
print(f"Native Numerals Text: {transliterated_text}")

Native Numerals Text: मुझे कल सुबह साढ़े नौ बजे अपॉइंटमेंट है

Spoken Form Numerals Language

spoken_form_numerals_language is an optional parameter with two options and only works when spoken_form is true:

• english: Numbers in the text will be spoken in English.
• native (default): Numbers in the text will be spoken in the native language.

Example:

Input: "मेरे पास ₹200 है"

• If english format is selected → "मेरे पास टू हन्डर्ड रूपीस है".
• If native format is selected → "मेरे पास दो सौ रुपये है".

1
response = client.text.transliterate(
2
    input="मुझे कल 9:30am को appointment है",
3
    source_language_code="hi-IN",
4
    target_language_code="hi-IN",
5
    spoken_form=True,
6
    spoken_form_numerals_language="english",
7
)
8
9
transliterated_text = response.transliterated_text
10
print(f"Spoken Form Numerals Language Text: {transliterated_text}")

Spoken Form Numerals Language Text: मुझे कल नाइन थर्टी ए एम को अपॉइंटमेंट है

7. Error Handling

You may encounter these errors while using the API:

• 403 Forbidden (invalid_api_key_error)

  • Cause: Invalid API key.
  • Solution: Use a valid API key from the Sarvam AI Dashboard.

• 429 Too Many Requests (insufficient_quota_error)

  • Cause: Exceeded API quota.
  • Solution: Check your usage, upgrade if needed, or implement exponential backoff when retrying.

• 500 Internal Server Error (internal_server_error)

  • Cause: Issue on our servers.
  • Solution: Try again later. If persistent, contact support.

• 400 Bad Request (invalid_request_error)

  • Cause: Incorrect request formatting.
  • Solution: Verify your request structure and parameters.

8. Additional Resources

For more details, refer to the our official documentation and we are always there to support and help you on our Discord Server:

• Documentation: docs.sarvam.ai
• Community: Join the Discord Community

9. Final Notes

• Keep your API key secure.
• Use clear audio for best results.
• Explore advanced features like diarization and translation.

Keep Building! 🚀