---
sidebar_position: 1
---

# Introduction to CaDaR

<div className="text-center">
  <h2 className="text-2xl font-bold mb-4">High-performance bidirectional transliteration for Darija</h2>
  
  <div className="grid grid-cols-1 md:grid-cols-3 gap-6 my-8">
    <div className="card">
      <div className="card__header">
        <h3>🔄 Bidirectional</h3>
      </div>
      <div className="card__body">
        <p>Seamlessly convert between Arabic and Latin scripts with perfect round-trip preservation.</p>
      </div>
    </div>
    
    <div className="card">
      <div className="card__header">
        <h3>⚡ High Performance</h3>
      </div>
      <div className="card__body">
        <p>Built with Rust for optimal speed (~1-2ms per sentence) and memory efficiency.</p>
      </div>
    </div>
    
    <div className="card">
      <div className="card__header">
        <h3>🎯 Darija-Aware</h3>
      </div>
      <div className="card__body">
        <p>Understands Darija-specific patterns, clitics, and linguistic constructs.</p>
      </div>
    </div>
  </div>
</div>

## Quick Demo

```python
import cadar

# Arabic to Latin
print(cadar.ara2bizi("سلام عليكم", darija="Ma"))
# Output: "salam 3likom"

# Latin to Arabic
print(cadar.bizi2ara("kifash dayer?", darija="Ma"))
# Output: "كيفاش داير؟"

# Standardize text
print(cadar.standardize("salaaaam bzaaaaf", script="auto", darija="Ma"))
# Output: "salam bzaf"
```

## Why CaDaR?

### The Challenge

Moroccan Arabic (Darija) presents unique transliteration challenges:

- **Mixed writing systems**: People switch between Arabic script, Latin script, and numerals within the same text
- **Darija-specific sounds**: No standard one-to-one mapping for many sounds (e.g., 3 for ع, 7 for ح)
- **Context-dependent mappings**: Same Latin character can map to different Arabic letters based on context
- **Informal variations**: Repeated characters, missing vowels, and creative spellings are common

### The Solution: ICR

CaDaR solves these challenges with its **Intermediate Canonical Representation (ICR)** - a script-independent, phonologically-grounded representation that:

```mermaid
graph LR
    A[Arabic/Latin Input] --> B[Script Detection]
    B --> C[Normalization]
    C --> D[Tokenization]
    D --> E[ICR Building]
    E --> F[Script Generation]
    F --> G[Output]
```

### What Makes CaDaR Different?

| Feature | CaDaR | Other Solutions |
|---------|-------|----------------|
| **Bidirectional** | ✅ Perfect round-trip | ⚠️ Often lossy |
| **Context-Aware** | ✅ Handles dependencies | ❌ Character-by-character |
| **Darija-Specific** | ✅ Built for Darija | ⚠️ Generic Arabic |
| **Performance** | ✅ ~1-2ms/sentence | ⚠️ Slower alternatives |
| **Standardization** | ✅ Removes noise | ❌ Limited support |

## Use Cases

### Social Media & Chat
Normalize user messages regardless of how they write:

```python
def normalize_message(msg):
    return cadar.standardize(msg, script="auto", darija="Ma")

# All normalize to: "salam lkhir"
messages = ["salaaam lkhiir", "سلاام الخير", "salam 5ir"]
```

### Content Moderation
Detect inappropriate content regardless of script:

```python
def detect_bad_words(text):
    # Convert to Latin for easier pattern matching
    latin = cadar.ara2bizi(text, darija="Ma")
    return check_patterns(latin)
```

### Search & Indexing
Index content consistently regardless of input script:

```python
def index_document(doc):
    # Store in canonical Latin form
    return cadar.standardize(doc, script="latin", darija="Ma")
```

### Educational Tools
Help learners understand script relationships:

```python
def teach_transliteration(word):
    arabic = cadar.bizi2ara(word, darija="Ma")
    back_to_latin = cadar.ara2bizi(arabic, darija="Ma")
    return f"{word} → {arabic} → {back_to_latin}"
```

## Key Features

### ✅ Smart Character Mapping
- Context-aware handling of emphatic consonants
- Proper clitic attachment (e.g., `fl` → `فال`, not `ف ل`)
- Number representations (3→ع, 7→ح, 8→غ, 9→ق)
- Special sequences (Dr→ض, ch→ش)

### ✅ Intelligent Normalization
- Removes duplicate characters and excessive spacing
- Handles diacritics and vocalization marks
- Preserves meaning while standardizing form

### ✅ Vowel Intelligence
- Distinguishes long and short vowels
- Position-aware vowel writing
- Darija mode for readability

### ✅ Performance Optimized
- Rust core for speed
- Linear scaling with input size
- Memory-efficient processing

## Get Started

```bash
pip install cadar
```

Then see our [Quick Start Guide](./getting-started/quickstart) for detailed installation and basic usage instructions.

## What's Next?

- [Explore the Python API](./user-guide/python-api)
- [See real-world examples](./user-guide/examples)
- [Understand the architecture](./architecture/pipeline)
- [Try the live playground](/playground)

---

<div className="text-center mt-8">
  <a href="./getting-started/installation" className="button button--primary button--lg">
    Get Started Now →
  </a>
</div>