# Hebrew & Arabic Text Toolkit: Normalize, Num2Words, Gematria (`harushlabs/hebrew-arabic-text-toolkit`) Actor

Batch Hebrew & Arabic text utilities for developers and AI agents: remove niqqud/tashkeel and normalize for search & RAG, amount in words for invoices and cheques (₪, $, €, SAR), Hebrew numerals (תשפ״ז), gematria, wrong-keyboard-layout fix, script detection. Pure computation.

- **URL**: https://apify.com/harushlabs/hebrew-arabic-text-toolkit.md
- **Developed by:** [Harush Studio](https://apify.com/harushlabs) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$1.00 / 1,000 text processeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Hebrew & Arabic Text Toolkit: Normalize, Number to Words, Gematria

Fast batch utilities for **Hebrew and Arabic text** that general-purpose tools get wrong. Built for developers, no-code automations (Make, Zapier, n8n) and **AI agents via MCP**.

| Operation | Example input | Example output |
| --- | --- | --- |
| `normalize` – for search, deduplication, RAG and embeddings | `בְּרֵאשִׁית בָּרָא` / `السَّلَامُ عَلَيْكُمْ ١٢٣` | `בראשית ברא` / `السلام عليكم 123` |
| `numberToWords` – **amount in words** for invoices, receipts and cheques | `1234.50` (ILS) | `אלף מאתיים שלושים וארבעה שקלים וחמישים אגורות` |
| `numberToWords` (Arabic) | `2.25` (SAR) | `اثنان ريالان و خمس و عشرون هللة` |
| `hebrewNumeral` – Hebrew-letter numbers for dates, chapters, lists | `5787` | `תשפ״ז` |
| `gematria` – standard, gadol and katan | `שלום` | `376` |
| `fixKeyboardLayout` – text typed in the wrong layout | `akuo` / `יקךךם` | `שלום` / `hello` |
| `detect` – script, direction, niqqud/tashkeel presence | `שלום עולם hello` | `{"script":"mixed","direction":"rtl",…}` |

### Why

- **Search & RAG**: vowelled (niqqud) Hebrew and harakat Arabic don't match unvowelled queries; Arabic letter variants (أ/إ/ا, ى/ي, ة/ه), tatweel (ـ), Arabic-Indic digits and presentation-form ligatures from PDFs break exact matching and embeddings. `normalize` fixes all of these with switchable options.
- **Finance & invoicing**: Israeli and Arab-market documents often require the amount in words. Hebrew grammar (gender agreement: *שקל אחד, שני שקלים, אגורה אחת, שתי אגורות*) is handled correctly.
- **Judaica, calendars, education**: Hebrew numerals with geresh/gershayim (ט״ו, ט״ז special cases) and gematria.
- **Support & forms**: repair text typed with the wrong keyboard layout (Israeli SI-1452 ↔ US QWERTY).

### Input example

```json
{
  "operation": "numberToWords",
  "numberMode": "currency",
  "currency": "ILS",
  "texts": ["1", "2", "1234.50", "0.02", "₪ 1,000"]
}
```

### Output example

```json
[
  { "index": 0, "operation": "numberToWords", "input": "1", "result": "שקל אחד", "status": "ok" },
  { "index": 1, "operation": "numberToWords", "input": "2", "result": "שני שקלים", "status": "ok" },
  { "index": 2, "operation": "numberToWords", "input": "1234.50", "result": "אלף מאתיים שלושים וארבעה שקלים וחמישים אגורות", "status": "ok" },
  { "index": 3, "operation": "numberToWords", "input": "0.02", "result": "שתי אגורות", "status": "ok" }
]
```

Invalid items return `"status": "error"` with a message and are **not charged**.

### Options

- `normalize`: `removeDiacritics`, `unifyArabicLetters`, `replaceHebrewFinalLetters`, `asciiDigits`, `asciiPunctuation`
- `numberToWords`: `numberLanguage` (he/ar), `numberMode` (cardinal/ordinal/currency), `currency` (Hebrew: ILS, USD, EUR, GBP; Arabic: SAR, EGP, KWD, TND), `hebrewGender`
- `gematria`: `gematriaMethod` (standard/gadol/katan)
- `hebrewNumeral`: `omitThousands` (5787 → תשפ״ז or ה׳תשפ״ז)
- `fixKeyboardLayout`: `layoutDirection` (auto / en->he / he->en)

### Pricing

**$0.001 per text processed** ($1 per 1,000). Errors are free. Up to 100,000 texts per run.

### Use from AI agents (MCP)

Add the Actor to the [Apify MCP server](https://mcp.apify.com) and your agent (Claude, Cursor, ChatGPT connectors, LangGraph…) can call it as a tool: *"write 1,234.50 shekels in Hebrew words"*.

### Notes

- Hebrew number words follow standard modern Hebrew; review legal documents as usual.
- Arabic number words come from the open-source [num2words](https://github.com/savoirfairelinux/num2words) library (LGPL-2.1, used unmodified).
- No data leaves the run; texts are not logged.

# Actor input Schema

## `operation` (type: `string`):

What to do with each text.

## `texts` (type: `array`):

One item per text (or number). Up to 100,000 items, 100,000 characters each.

## `removeDiacritics` (type: `boolean`):

normalize: strips Hebrew vowel points & cantillation and Arabic harakat.

## `unifyArabicLetters` (type: `boolean`):

normalize: أ/إ/آ→ا, ى→ي, ة→ه, ؤ→و, ئ→ي (common for Arabic search indexing).

## `replaceHebrewFinalLetters` (type: `boolean`):

normalize: ך→כ, ם→מ, ן→נ, ף→פ, ץ→צ.

## `asciiDigits` (type: `boolean`):

normalize: ١٢٣ / ۱۲۳ → 123.

## `asciiPunctuation` (type: `boolean`):

normalize: maqaf, geresh/gershayim, Arabic comma/question mark and curly quotes to ASCII.

## `numberLanguage` (type: `string`):

numberToWords: output language.

## `numberMode` (type: `string`):

numberToWords: style.

## `currency` (type: `string`):

numberToWords currency mode. Hebrew: ILS, USD, EUR, GBP. Arabic: SAR, EGP, KWD, TND.

## `hebrewGender` (type: `string`):

numberToWords cardinal in Hebrew.

## `gematriaMethod` (type: `string`):

gematria: calculation method.

## `omitThousands` (type: `boolean`):

hebrewNumeral: 5787 → תשפ״ז (calendar style) instead of ה׳תשפ״ז.

## `layoutDirection` (type: `string`):

fixKeyboardLayout: Israeli SI-1452 ↔ US QWERTY.

## Actor input object example

```json
{
  "operation": "normalize",
  "texts": [
    "בְּרֵאשִׁית בָּרָא אֱלֹהִים",
    "السَّلَامُ عَلَيْكُمْ ١٢٣"
  ],
  "removeDiacritics": true,
  "unifyArabicLetters": false,
  "replaceHebrewFinalLetters": false,
  "asciiDigits": true,
  "asciiPunctuation": true,
  "numberLanguage": "he",
  "numberMode": "cardinal",
  "currency": "ILS",
  "hebrewGender": "m",
  "gematriaMethod": "standard",
  "omitThousands": true,
  "layoutDirection": "auto"
}
```

# Actor output Schema

## `results` (type: `string`):

Dataset with one item per input text: index, input, result, status and error.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "texts": [
        "בְּרֵאשִׁית בָּרָא אֱלֹהִים",
        "السَّلَامُ عَلَيْكُمْ ١٢٣"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("harushlabs/hebrew-arabic-text-toolkit").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "texts": [
        "בְּרֵאשִׁית בָּרָא אֱלֹהִים",
        "السَّلَامُ عَلَيْكُمْ ١٢٣",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("harushlabs/hebrew-arabic-text-toolkit").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "texts": [
    "בְּרֵאשִׁית בָּרָא אֱלֹהִים",
    "السَّلَامُ عَلَيْكُمْ ١٢٣"
  ]
}' |
apify call harushlabs/hebrew-arabic-text-toolkit --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,harushlabs/hebrew-arabic-text-toolkit"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/Dc6U45t2IKdaMfocV/builds/3i29RIXb293Hwvavo/openapi.json