# Torah and Chassidus Translate - Complete User Guide

Version 1.0.6 (98) documentation edition - July 2026

## What the app is for

Torah and Chassidus Translate helps learners, teachers, translators, and researchers turn photographed or scanned Hebrew and Yiddish source pages into a reviewable study workspace. A project keeps the original page, OCR text, translation history, source references, study tools, exports, and optional tutoring together.

The app is an aid to learning and editorial work. AI output can be incomplete or wrong. Compare the translation with the source, inspect cited references, and consult a qualified teacher or editor for consequential interpretation.

## The basic workflow

1. Create a project for one work, topic, class, or research task.
2. Add pages from the camera, photos, files, or a PDF.
3. Crop and rotate the page so the complete text is legible.
4. Choose a provider, model, output language, and translation template.
5. Translate one test page before starting a larger batch.
6. Review source and translation side by side. Correct OCR or identity metadata when needed.
7. Use Word Lens, Reader, source inspection, summaries, tags, or the project-grounded tutor to study the result.
8. Export a content-specific PDF, Markdown, DOCX, or other supported format, then protect the project with backup.

## 1. Create and organize a project

From the library, choose **New Project**. Use a title that will remain meaningful later, such as the work, chapter, class, or theme. Add a short source description if it helps distinguish editions or teaching goals.

Projects show page count, translation status, tags, and items needing attention. Tags can describe work, topic, sefer, chapter, difficulty, or review status. Keep one coherent source or learning goal per project when possible; this improves browsing and gives the tutor clearer context.

![A project created from an authenticated test import](../website/assets/images/docs/v1.0.6/ipad-03-library-project.png)

## 2. Configure an AI provider

Open **Settings > AI Providers & Models**. The app supports bring-your-own-key provider configuration, including Google Gemini. Enter the key, save it, and use the provider test before translating.

Provider keys are stored through the operating system's secure credential storage. They should never be placed in a project title, prompt template, exported document, screenshot, support email, or shared backup note. Provider requests and billing remain subject to that provider's terms, quotas, retention rules, and prices.

The green **Ready** state confirms that the app can authenticate and load the provider's model catalog. It does not promise that every model is available to the account or free to use.

![Gemini readiness with the key masked](../website/assets/images/docs/v1.0.6/ipad-02-gemini-ready.png)

## 3. Import pages and PDFs

Use a sharp, evenly lit photograph or a clean PDF. Include the whole page and avoid fingers, glare, curved gutters, and clipped margins. For a large PDF, preview the range and import only the pages needed for the current task before committing to a full run.

The app retains the original and edited page image. OCR text can be reviewed and corrected without changing the photographed source. Printed page identity is different from a volume label: a standalone number such as `361` is treated as a printed page unless the source explicitly says Volume, Vol., כרך, or חלק.

For the authenticated documentation test, the app imported an original one-page Hebrew learning sample, stored the page, and used verified source text for the translation run. No copyrighted book page or private user material was used.

## 4. Translate carefully

The run configuration records the provider, model, prompt template, output language, input mode, and quality mode. Start with one representative page. Review it before translating selected pages or a whole project.

Parallel bilingual view keeps the image, source text, and translation visible together. Translation history is preserved when the provider, model, template, source text, or image changes, so an earlier result can be compared or restored.

![Authenticated Gemini translation beside its original Hebrew source](../website/assets/images/docs/v1.0.6/ipad-05-parallel-translation.png)

Review these items before treating a page as finished:

- Page and volume identity match explicit evidence in the source.
- Paragraph order and headings match the page.
- Names, quotations, and technical terms are preserved consistently.
- Brackets, transliterations, and explanatory additions are distinguishable from the source.
- Source references resolve to the intended work and location.
- The result does not omit text from the bottom, margin, or second column.

## 5. Learn with the result

The learning tools are most useful after the source and translation are reviewable.

- **Word Lens** explains a selected Hebrew or Yiddish term and can show translation context or saved glossary meaning.
- **Reader Mode** reduces visual clutter for sustained reading.
- **Text to speech** reads available text using the selected voice.
- **Summaries and tags** create navigational aids at beginner, advanced, or scholar depth.
- **Review items** turn saved passages or questions into material to revisit.
- **Study with tutor** grounds typed or live conversation in the current project or page.

The tutor should help a learner ask for a simpler reading, compare two concepts, locate support on the page, or take a short comprehension check. It should not replace reading the source. Ask it to cite the page and verify the cited passage in the viewer.

Before cloud tutoring begins, the app explains that questions, audio, and selected excerpts may be sent to the chosen provider and may incur provider charges. The provider key remains in secure device storage rather than being sent to the Torah Translate backend.

![Cloud tutoring consent shown before a Gemini session](../website/assets/images/docs/v1.0.6/ipad-06-study-with-tutor.png)

## 6. Understand cost and privacy

Bring-your-own-key calls are billed by the selected provider. The app records planning estimates and token or modality details when the provider reports them; the provider invoice is authoritative. Voice can include text input, text output, audio input, audio output, cached input, or transcription usage. A live-session warning or budget cannot be enforced when a provider/model price is unavailable.

Use local models when available for compatible offline tasks. Local operation can reduce cloud disclosure and provider charges, but it uses device storage, memory, battery, and downloaded model assets. Local quality and language coverage can differ from cloud models.

Treat scans, translations, transcripts, notes, and exports as potentially sensitive. Disable saved tutor transcripts when a session should remain ephemeral. Remember that saved app data may be included in a configured encrypted backup or device sync.

## 7. Export and protect the work

Choose the export that matches the next task:

- **Reader PDF** for a polished reading copy.
- **Study Reader PDF** for source-aware learning and review.
- **Markdown or DOCX** for editing and teaching material.
- **ZIP** for portable project backup.
- **XLIFF, TMX, or CSV** for translation and terminology workflows.

Export filenames are derived from the project and content identity rather than a generic name. Inspect the exported title, page order, right-to-left text, footnotes, and images before distributing it.

Configure backup after the first meaningful project. A local app install, a provider account, and a project backup are separate things; reinstalling the app is not a backup strategy.

## 8. Troubleshooting checklist

- **Provider rejected the key:** confirm the key belongs to the selected provider, is enabled, and has quota. Run the provider test in Settings.
- **Page is incomplete or out of order:** recrop, rotate, or re-import the page and check OCR text before translating again.
- **Wrong page or volume label:** edit identity metadata and keep only labels explicitly supported by the page or project.
- **Malformed or weak translation:** retry the page, use a different model or template, or repair OCR first.
- **Voice cannot start on iOS:** end competing call, Siri, or Bluetooth voice sessions; stop and reconnect. The app should pause a live session when the shared audio route is unavailable.
- **Cost unavailable:** select a model with a known rate card or rely on the provider console rather than assuming zero cost.
- **Export looks wrong:** preview the document, confirm source order and right-to-left layout, then export again after corrections.

## Documentation test record

This guide's authenticated screenshots were produced on a disposable iPad simulator with version 1.0.6 (98). The test:

1. Stored a temporary Gemini credential in secure app storage.
2. Created **A Journey Into Chassidic Thought**.
3. Imported an original Hebrew sample image through the production image-import service.
4. Saved verified Hebrew source text and explicit printed-page metadata.
5. Requested a real translation from `gemini-3.1-flash-lite` through the production translation service.
6. Verified that a completed Gemini translation was persisted.
7. Captured the real library, project, page, tutor-consent, and provider-settings screens.

The temporary key is not present in the repository, screenshots, documentation, or distributed artifacts. Provider behavior and model availability may change after this test.