---
title: Translation
description: Translate text between Amharic, Afaan Oromo, and English.
icon: Languages
---

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { TypeTable } from 'fumadocs-ui/components/type-table';
import { Callout } from 'fumadocs-ui/components/callout';
import { Globe, RefreshCw, BookA, ShieldCheck } from 'lucide-react';


The Translation API supports bidirectional translation between Amharic (`am`), Afaan Oromo (`om`), and English (`en`). All six source-to-target language combinations are available through the REST API and official SDKs.
## Use Cases

<div className="addis-offset-shell addis-grid grid-cols-1 md:grid-cols-3 mb-10">
  <div className="p-4 border border-fd-border rounded-lg bg-fd-card">
    <div className="flex items-center gap-2 mb-2 font-bold text-fd-foreground">
      <Globe className="w-4 h-4 text-fd-muted-foreground" /> Public Service
    </div>
    <div className="text-xs text-fd-muted-foreground">
      Automatically translate government forms, announcements, and news between Amharic and Afaan Oromo to reach wider audiences.
    </div>
  </div>
  
  <div className="p-4 border border-fd-border rounded-lg bg-fd-card">
    <div className="flex items-center gap-2 mb-2 font-bold text-fd-foreground">
      <RefreshCw className="w-4 h-4 text-fd-muted-foreground" /> Marketplace
    </div>
    <div className="text-xs text-fd-muted-foreground">
      Enable real-time chat translation between buyers and sellers who speak different local languages or English.
    </div>
  </div>

  <div className="p-4 border border-fd-border rounded-lg bg-fd-card">
    <div className="flex items-center gap-2 mb-2 font-bold text-fd-foreground">
      <BookA className="w-4 h-4 text-fd-muted-foreground" /> Education
    </div>
    <div className="text-xs text-fd-muted-foreground">
      Translate educational materials and technical documentation from English into local languages to improve accessibility.
    </div>
  </div>
</div>

---

## Usage Guide

### Basic Translation
Translate text between any of the supported languages (`am`, `om`, `en`).

<Tabs items={['Node.js', 'Python', 'cURL']}>
  <Tab value="Node.js">
    ```ts
    import AddisAI from "addisai";

    const addis = new AddisAI();
    const result = await addis.translate.create({
      text: "ገበሬው ማሳውን ዘወትር ይጎበኛል",
      from: "am",
      to: "om",
    });

    console.log(result.text);
    ```
  </Tab>
  <Tab value="Python">
    ```python
    from addisai import AddisAI

    addis = AddisAI()
    result = addis.translate.create(
        text="ገበሬው ማሳውን ዘወትር ይጎበኛል",
        source="am",
        target="om",
    )

    print(result["text"])
    ```
  </Tab>
  <Tab value="cURL">
    ```bash
    curl --location 'https://api.addisassistant.com/api/v1/translate' \
      --header 'Content-Type: application/json' \
      --header "x-api-key: $ADDIS_API_KEY" \
      --data '{
        "text": "ገበሬው ማሳውን ዘወትር ይጎበኛል",
        "source_language": "am",
        "target_language": "om"
      }'
    ```
  </Tab>
</Tabs>

#### Available Parameters

| Value | Node.js | Python | REST | Required |
| :--- | :--- | :--- | :--- | :--- |
| Text to translate | `text` | `text` | `text` | Yes |
| Source language | `from` | `source` | `source_language` | Yes: `am`, `om`, or `en` |
| Target language | `to` | `target` | `target_language` | Yes: `am`, `om`, or `en` |

Source and target must be different. Translation is supported in both directions between Amharic, Afaan Oromo, and English.

---

## API Reference

### Request Parameters

<TypeTable
  type={{
    'text': {
      description: 'The content to be translated. Max 2000 characters per request.',
      type: 'string',
      required: true
    },
    'source_language': {
      description: 'Input language code ("am", "om", "en").',
      type: 'string',
      required: true
    },
    'target_language': {
      description: 'Output language code ("am", "om", "en").',
      type: 'string',
      required: true
    }
  }}
/>

### Response Schema

```json
{
    "status": "success",
    "data": {
        "translation": "Qotee bulaan yeroo mara maasaa isaa ni daawwata.",
        "source_language": "am",
        "target_language": "om",
        "quality": "high",
        "usage_metadata": {
            "prompt_token_count": 113,
            "candidates_token_count": 57,
            "total_token_count": 170
        }
    }
}
```
<TypeTable
type={{
'status': {
description: 'Request status (e.g., "success").',
type: 'string'
},
'data': {
description: 'Container for the translation results.',
type: 'object'
},
'data.translation': {
description: 'The resulting translated string.',
type: 'string'
},
'data.quality': {
description: 'Confidence level of the translation.',
type: 'string'
},
'data.usage_metadata': {
description: 'Token usage statistics.',
type: 'object'
}
}}
/>
---
## Best Practices
Ensure the highest quality translations with these guidelines.
<div className="addis-offset-shell addis-grid grid-cols-1 md:grid-cols-2 mt-10">
{/* Input Quality */}
<div className="flex flex-col p-5 rounded-lg border border-fd-border bg-fd-card shadow-sm transition-all hover:border-fd-primary/30">
<div className="flex items-center gap-2.5 mb-4">
<ShieldCheck className="w-4 h-4 text-fd-muted-foreground" />
<h3 className="font-semibold text-sm text-fd-foreground uppercase tracking-wide">Input Fidelity</h3>
</div>
<div className="space-y-3 text-sm text-fd-muted-foreground">
<div>
<strong className="text-fd-foreground">Spelling Matters:</strong> Ensure the source text has correct spelling. For Amharic, consistency in Fidel usage (e.g., using `ሠ` vs `ሰ` correctly) improves output quality.
</div>
<div>
<strong className="text-fd-foreground">Punctuation:</strong> Include proper punctuation (`።`, `?`) to help the model understand sentence boundaries.
</div>
</div>
</div>
{/* Language Pairs */}
<div className="flex flex-col p-5 rounded-lg border border-fd-border bg-fd-card shadow-sm transition-all hover:border-fd-primary/30">
<div className="flex items-center gap-2.5 mb-4">
<RefreshCw className="w-4 h-4 text-fd-muted-foreground" />
<h3 className="font-semibold text-sm text-fd-foreground uppercase tracking-wide">Supported Languages</h3>
</div>
<div className="space-y-3 text-sm text-fd-muted-foreground">
<div>
<strong className="text-fd-foreground">Supported language pairs</strong>
</div>
<div className="flex flex-wrap gap-2">
<code className="bg-fd-secondary px-2 py-1 rounded text-xs">Amharic ↔ Afaan Oromo</code>
<code className="bg-fd-secondary px-2 py-1 rounded text-xs">Amharic ↔ English</code>
<code className="bg-fd-secondary px-2 py-1 rounded text-xs">Afaan Oromo ↔ English</code>
</div>
</div>
</div>
{/* Context */}
<div className="flex flex-col p-5 rounded-lg border border-fd-border bg-fd-card shadow-sm transition-all hover:border-fd-primary/30">
<div className="flex items-center gap-2.5 mb-4">
<BookA className="w-4 h-4 text-fd-muted-foreground" />
<h3 className="font-semibold text-sm text-fd-foreground uppercase tracking-wide">Context</h3>
</div>
<div className="space-y-3 text-sm text-fd-muted-foreground">
<div>
<strong className="text-fd-foreground">Full Sentences:</strong> Avoid translating single words in isolation if possible. Context helps resolve ambiguities (e.g., "eye" vs "spring" in Amharic).
</div>
</div>
</div>
</div>