---
sidebar_position: 2
---

# Quick Start

This guide will get you up and running with CaDaR in 5 minutes. We'll cover the basics of bidirectional transliteration between Arabic and Latin scripts for Moroccan Darija.

## Basic Usage

### 1. Import CaDaR

```python
import cadar
```

### 2. Core Functions

CaDaR provides four main functions for transliteration and standardization:

```python
# Arabic to Latin (Bizi)
arabic_text = "سلام عليكم"
latin_result = cadar.ara2bizi(arabic_text, darija="Ma")
print(f"{arabic_text} → {latin_result}")
# Output: سلام عليكم → salam 3likom

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

### 3. Standardization

Clean up noisy or inconsistent text:

```python
# Standardize Arabic (remove diacritics, etc.)
messy_arabic = "أنَا مِنْ المَغْرِب"
clean_arabic = cadar.ara2ara(messy_arabic, darija="Ma")
print(f"{messy_arabic} → {clean_arabic}")
# Output: أنَا مِنْ المَغْرِب → انا من المغرب

# Standardize Latin (remove repeats, etc.)
messy_latin = "salaaaam bzaaaaf"
clean_latin = cadar.bizi2bizi(messy_latin, darija="Ma")
print(f"{messy_latin} → {clean_latin}")
# Output: salaaaam bzaaaaf → salam bzaf
```

## Convenience Functions

For easier usage, CaDaR provides auto-detection functions:

```python
# Auto-detect and transliterate
text1 = "سلام"  # Arabic
result1 = cadar.transliterate(text1, target="latin", darija="Ma")
print(f"{text1} → {result1}")

text2 = "salam"  # Latin
result2 = cadar.transliterate(text2, target="arabic", darija="Ma")
print(f"{text2} → {result2}")

# Auto-detect and standardize
text3 = "salaaaam"
result3 = cadar.standardize(text3, script="auto", darija="Ma")
print(f"{text3} → {result3}")
```

## Using the CaDaR Class

For multiple operations, create a reusable processor:

```python
# Create processor with default Moroccan dialect
processor = cadar.CaDaR(darija="Ma")
print(f"Using dialect: {processor.get_dialect()}")

# Use multiple times
texts = ["سلام", "kifash", "بزاف"]
for text in texts:
    if any('\u0600' <= c <= '\u06FF' for c in text):
        # It's Arabic
        print(f"{text} → {processor.ara2bizi(text)}")
    else:
        # It's Latin
        print(f"{text} → {processor.bizi2ara(text)}")
```

## Common Patterns

### Social Media Messages

```python
def normalize_chat_message(message):
    """Normalize any chat message to standard Latin form"""
    return cadar.standardize(message, script="latin", darija="Ma")

# Examples
messages = [
    "salaaaam 3likooooom",  # Repeated characters
    "السَّلاَمْ عَلَيْكُمْ",  # With diacritics
    "salam lkhir",          # Already clean
]

for msg in messages:
    print(f"{msg:25s} → {normalize_chat_message(msg)}")
```

Output:
```
salaaaam 3likooooom   → salam 3likom
السَّلاَمْ عَلَيْكُمْ     → salam 3likom
salam lkhir           → salam lkhir
```

### Content Moderation

```python
def contains_bad_word(text):
    """Check for inappropriate content regardless of script"""
    # Convert to Latin for easier pattern matching
    latin = cadar.ara2bizi(text, darija="Ma") if has_arabic(text) else text
    bad_words = ["bad1", "bad2", "bad3"]
    return any(word in latin.lower() for word in bad_words)

def has_arabic(text):
    return any('\u0600' <= c <= '\u06FF' for c in text)

# Test
test_messages = [
    "This is clean",
    "هذا نظيف",
    "bad1 content",
    "bad1 بالعربية",
]

for msg in test_messages:
    status = "⚠️ Flagged" if contains_bad_word(msg) else "✅ OK"
    print(f"{msg:20s} - {status}")
```

### Search Indexing

```python
def create_search_key(text):
    """Create a consistent search key regardless of input script"""
    return cadar.standardize(text, script="latin", darija="Ma")

# Documents in various forms
documents = [
    {"title": "مرحبا", "content": "أهلا بكم"},
    {"title": "Ahlan", "content": "Welcome"},
    {"title": "أهلاً", "content": "Hello everyone"},
]

# Create searchable index
index = {}
for doc in documents:
    # Create search keys from title and content
    title_key = create_search_key(doc["title"])
    content_key = create_search_key(doc["content"])
    index[doc["title"]] = {
        "title_key": title_key,
        "content_key": content_key,
        "original": doc
    }

# Search function
def search(query):
    query_key = create_search_key(query)
    results = []
    for title, data in index.items():
        if query_key in data["title_key"] or query_key in data["content_key"]:
            results.append(data["original"])
    return results

# Test searches
for query in ["ahlan", "أهلا", "hello"]:
    print(f"\nSearching for: {query}")
    results = search(query)
    for result in results:
        print(f"  Found: {result}")
```

## Round-Trip Conversion

Test the quality of transliteration with round-trip conversion:

```python
def test_round_trip(text):
    """Test if text survives round-trip conversion"""
    # Convert to other script and back
    if has_arabic(text):
        intermediate = cadar.ara2bizi(text, darija="Ma")
        back = cadar.bizi2ara(intermediate, darija="Ma")
    else:
        intermediate = cadar.bizi2ara(text, darija="Ma")
        back = cadar.ara2bizi(intermediate, darija="Ma")
    
    # Compare standardized forms
    orig_std = cadar.standardize(text, script="auto", darija="Ma")
    back_std = cadar.standardize(back, script="auto", darija="Ma")
    
    return orig_std == back_std, (text, intermediate, back)

# Test various texts
test_texts = [
    "salam 3likom",
    "كيفاش داير؟",
    "ma kan3rfch",
    "ما كنعرفش",
    "bzzaf dial l7yan"
]

print("Round-trip tests:")
print("-" * 50)
for text in test_texts:
    success, (orig, inter, back) = test_round_trip(text)
    status = "✅" if success else "❌"
    print(f"{status} {orig:20s} → {inter:20s} → {back}")
```

## Performance Tips

### Batch Processing

For multiple texts, reuse the processor:

```python
# Inefficient: creates new processor each time
results = [cadar.ara2bizi(text, darija="Ma") for text in texts]

# Efficient: reuse processor
processor = cadar.CaDaR(darija="Ma")
results = [processor.ara2bizi(text) for text in texts]
```

### Memory Usage

CaDaR is memory-efficient, but for very large texts:

```python
# For huge files, process in chunks
def process_large_file(input_path, output_path):
    processor = cadar.CaDaR(darija="Ma")
    with open(input_path, 'r', encoding='utf-8') as infile, \
         open(output_path, 'w', encoding='utf-8') as outfile:
        for line in infile:
            processed = processor.ara2bizi(line.strip())
            outfile.write(processed + '\n')
```

## Common Pitfalls

### 1. Forgetting the Dialect Parameter

```python
# ❌ Wrong - will use default (which may not be what you want)
result = cadar.ara2bizi("سلام")

# ✅ Correct - explicitly specify
result = cadar.ara2bizi("سلام", darija="Ma")
```

### 2. Mixing Scripts

CaDaR handles mixed scripts, but for best results:

```python
# This works but may be slower
mixed = "salam كيفاش"
result = cadar.standardize(mixed, script="auto", darija="Ma")

# Better to know your input
if has_arabic(mixed):
    result = cadar.ara2ara(mixed, darija="Ma")
else:
    result = cadar.bizi2bizi(mixed, darija="Ma")
```

### 3. Expecting Perfect One-to-One Mapping

```python
# ❌ This may not work as expected
# "k" could map to ك or ق depending on context

# ✅ Let CaDaR handle context
result = cadar.bizi2ara("kayn", darija="Ma")  # → كاين
```

## What's Next?

- [Explore the full Python API](../user-guide/python-api)
- [See more examples](../user-guide/examples)
- [Understand character mappings](../user-guide/character-mappings)
- [Learn about the architecture](../architecture/pipeline)
- [Try the interactive playground](/playground)

## Need Help?

- Check our [FAQ](../faq)
- Open an [issue on GitHub](https://github.com/Oit-Technologies/CaDaR/issues)
- Join our [discussions](https://github.com/Oit-Technologies/CaDaR/discussions)