# Hebrew & RTL text in generated images

Both Gemini models (Flash and Pro) and OpenAI gpt-image-1.5 have **unreliable Hebrew/Arabic rendering**. Letters drop, glyphs disconnect (Arabic), final-form letters (ך ם ן ף ץ) are missed, RTL ordering breaks. This is the #1 production-blocker for Hebrew-first work.

**The default workflow for Hebrew text in images is two-stage:**

1. Generate a **text-free image** with the model.
2. Composite Hebrew text on top in a deterministic tool (SVG/Canvas/Figma/Pillow).

Do not attempt to render Hebrew text inside the image-generation prompt unless the user explicitly opts in to risk + iteration.

## Risk assessment by use case

| Use case | Risk | Recommendation |
|---|---|---|
| Logo with Hebrew wordmark | High | Generate **mark only** (no text). Add wordmark in vector tool. |
| UI mockup with Hebrew labels | High | Generate UI **with English placeholder text** for client preview. For production assets, generate text-free and overlay Hebrew via DOM/Canvas. |
| Hero image with Hebrew headline | Very high | Generate scene only. Composite headline in design tool. |
| Hebrew on packaging / product mockup | High | Same as hero. |
| Marketing graphic with mixed Hebrew + English | Very high | Same as hero. |
| Decorative Hebrew script as visual element (not literal text) | Medium | OK to attempt with Gemini Pro at 4K. Quote the desired text exactly, request "Hebrew typography (right-to-left, modern sans-serif like Heebo or Assistant)." Sanity-check every output. |

## Two-stage workflow — the canonical recipe

### Stage 1: generate text-free image

Use Gemini Pro (best composition for design work) at the target final resolution.

Prompt pattern:
```
[Standard six-element prompt — subject, composition, action, location, style]

Composition note: leave a clean text area in the [top-left / center / bottom-right]
sized approximately [N%] of the canvas. The text area should be a [solid color / soft
gradient / blurred background] with no detail, suitable for overlaying a headline
in post-production. Do not render any text or typography in this image.
```

Save the result as the *background plate*.

### Stage 2: composite Hebrew text

Three options, in increasing fidelity:

**Option A: SVG overlay (web)**
```html
<div style="position: relative; width: 1920px; height: 1080px;">
  <img src="background-plate.png" style="position: absolute; inset: 0;" />
  <div dir="rtl" style="
    position: absolute;
    top: 80px; right: 80px;
    font-family: 'Heebo', 'Assistant', sans-serif;
    font-size: 96px;
    font-weight: 700;
    color: white;
    text-shadow: 0 2px 8px rgba(0,0,0,0.4);
  ">
    ברוכים הבאים לאג'נטלה
  </div>
</div>
```
Render to PNG via headless Chrome / Puppeteer if you need a static asset.

**Option B: Pillow (Python, deterministic, scriptable)**
```python
from PIL import Image, ImageDraw, ImageFont
import arabic_reshaper  # works for Hebrew too via bidi
from bidi.algorithm import get_display

img = Image.open("background-plate.png").convert("RGBA")
draw = ImageDraw.Draw(img)
font = ImageFont.truetype("/path/to/Heebo-Bold.ttf", 96)

text = "ברוכים הבאים לאג'נטלה"
display_text = get_display(text)  # applies BIDI algorithm
draw.text((1840, 80), display_text, font=font, fill="white", anchor="rt")

img.save("final.png")
```

**Option C: Figma (highest design fidelity, manual)**
- Place background plate as image fill in a frame.
- Add a text layer with `dir=rtl` (Figma respects this for Hebrew/Arabic fonts).
- Use Heebo, Assistant, Rubik, or another web-safe Hebrew font.
- Export as PNG / SVG.

## If you absolutely must render Hebrew inside the image

(Cases: client demo only, exploration, quick concept, willing to iterate.)

1. **Use Gemini Pro 4K, not Flash.** Flash's weaker text rendering will fail more often.
2. **Quote the Hebrew text exactly** and explicitly describe RTL:
   ```
   Render the Hebrew headline 'ברוכים הבאים' (Hebrew script, right-to-left,
   modern sans-serif typography like Heebo or Assistant, no nikud, bold weight).
   ```
3. **Sanity-check every output.** Common failure modes:
   - Letters rendering as lookalike Latin/Cyrillic glyphs (ב → b-shape)
   - Missing final-form letters (ך ם ן ף ץ rendered as their non-final forms)
   - Wrong letter order (read left-to-right instead of right-to-left)
   - Mirrored / disconnected glyphs
   - Random extra letters added
4. **Iterate up to 3 times.** If it's still wrong after 3 attempts, fall back to two-stage workflow. Don't burn $0.72 on more attempts.

## Hebrew web-safe font reference

Use these Hebrew-supporting fonts for the composite stage:

| Font | Use for | Source |
|---|---|---|
| **Heebo** | UI, body text | Google Fonts |
| **Assistant** | UI, headings | Google Fonts |
| **Rubik** | UI, marketing | Google Fonts |
| **Frank Ruhl Libre** | Editorial, serif | Google Fonts |
| **Suez One** | Display, headlines | Google Fonts |
| **Secular One** | Display, headings | Google Fonts |

Default to **Heebo Bold** for UI mockups and **Assistant** for body text — they match Israeli web design conventions.

## Mixed Hebrew + English text

When the design has both Hebrew and English (common in Israeli marketing):

- Generate the image text-free.
- Use a **single multilingual font** that supports both scripts (Heebo, Assistant, Rubik all do).
- Composite each text block separately, with `dir="rtl"` on Hebrew blocks and `dir="ltr"` on English blocks.
- Mind the visual weight balance — Hebrew letters tend to look heavier at the same size; bump English up by ~5-10% to match.

## Logos with Hebrew wordmarks — the brand-safe pipeline

1. Generate the **mark** (icon/symbol only) with Gemini Pro at 4K square. Prompt:
   ```
   [Brand brief]. Mark only — no text, no wordmark, no typography. Centered
   on pure white background, generous padding. Flat vector aesthetic, suitable
   for SVG conversion.
   ```
2. Vectorize the mark via Illustrator Image Trace, VectorizerAI, or hand-redraw.
3. Set the Hebrew wordmark in your design tool with a real Hebrew typeface (Heebo, Assistant, Rubik, or a custom typeface for premium brands).
4. Compose mark + wordmark in your locked brand layout.

This is the **only** pipeline that produces production-quality Hebrew logos.