all: --ocr-lang option through every surface

The OCR language switch was env-only (DOCLING_RS_OCR_LANG); plumb it
through the full option pattern like pages/video_frames:

- docling-pdf: OcrLang is now a public enum (parse / from_env);
  Pipeline::ocr_lang(Option<OcrLang>) + set_ocr_lang for the warm serve
  instance — a model switch, not pure configuration, so any worker whose
  cached recognition model was loaded for the other language drops it
  and lazily reloads (~10 MB model; verified live: ch request then
  default request on one warm pipeline produce ch-glued and en-spaced
  output respectively). Worker carries its lang; the one-shot
  convert_with_options/convert_image_with_options grow an
  ocr_lang: Option<OcrLang> arg.
- docling: DocumentConverter::ocr_lang(str) (unknown value warns and
  uses the default at convert time, same degradation as the env
  selector), threaded through StreamSettings into the streaming path;
  OcrLang re-exported.
- CLI: --ocr-lang en|ch (invalid value = usage error, exit 2).
- serve: ocr_lang option (multipart field + JSON key + query param),
  applied per request to the warm pipeline next to set_pages; invalid
  value → 422.
- Python: ocr_lang= kwarg on the native converter (typo → ValueError)
  and on the docling-shaped wrapper, which also maps
  ocr_options.lang lists (["english"]→en, ["chinese"]→ch, anything
  else warns and is ignored).
- Node: ocrLang option on ConvertOptions and Pipeline options
  (invalid → typed Error). Verified against the scanned tiff fixture
  from JS: ch glues, en spaces, xx throws.
- RAG keeps RAG_OCR_LANG (already mapped onto the engine env).

Docs: README OCR paragraph (per-surface list), serve API list (also adds
the previously undocumented pages line), node/py READMEs, MIGRATION.md
PDF row, CLI usage strings.

Signed-off-by: artiz <artem.kustikov@gmail.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EY5KAiquN4YpVf2PXEQkVT

Author: artiz

README.md

@@ -125,7 +125,7 @@ curl -H 'content-type: application/json' \
 ```
 
 Options per request: `to=md|json|dclx|chunks`, `strict`, `images=placeholder|embedded`,
-`no_ocr`, `no_table_former`, `fetch_images` — as query parameters, multipart
+`no_ocr`, `no_table_former`, `pages`, `ocr_lang`, `fetch_images` — as query parameters, multipart
 fields, or JSON keys (body wins). Server flags: `--addr`, `--concurrency`,
 `--max-body-mb`, `--warmup`, `--no-url-fetch`, `--strict`. A container image
 builds from [`crates/docling-serve/Dockerfile`](./crates/docling-serve/Dockerfile)
@@ -759,7 +759,11 @@ env var always wins over the `./models` / `./.pdfium` default.
 
 OCR recognition defaults to the **English** PP-OCRv3 model: the multilingual
 `ch_` model reads Latin text with broken word spacing (`Refactorexisting
-microservices writtenonJava`-style output on ordinary scans).
+microservices writtenonJava`-style output on ordinary scans). The switch
+plumbs through every surface — CLI `--ocr-lang en|ch`,
+`DocumentConverter::ocr_lang` / `Pipeline::ocr_lang`, serve `ocr_lang`
+option, Python `ocr_lang=` kwarg (also mapped from docling-shaped
+`ocr_options.lang`), Node `ocrLang` option — or process-wide,
 `DOCLING_RS_OCR_LANG=ch` selects the `ch_` pair — that's the model upstream
 docling conformance is measured against, and the conformance scripts pin it
 themselves; explicit `DOCLING_OCR_REC_ONNX`+`DOCLING_OCR_DICT` (a pair — set

crates/docling-cli/src/main.rs

@@ -3,7 +3,7 @@
 //! The docling.rs counterpart of `docling.cli.main`; `docling-rs serve`
 //! (with `--features serve`) starts the HTTP conversion API.
 //!
-//! Usage: docling-rs [--strict] [--to md|json] [--pages A-B] [--images MODE] [--fetch-images] [--no-stream] [--no-table-former] [--no-ocr] [--asr-model PRESET] [--video-frames N] [--use-web-browser] [--enrich-picture-classes] [--enrich-code] [--enrich-formula] <input-file>
+//! Usage: docling-rs [--strict] [--to md|json] [--pages A-B] [--images MODE] [--fetch-images] [--no-stream] [--no-table-former] [--no-ocr] [--ocr-lang en|ch] [--asr-model PRESET] [--video-frames N] [--use-web-browser] [--enrich-picture-classes] [--enrich-code] [--enrich-formula] <input-file>
 //!   --to md|json       output format (default: md). `json` emits docling-core's
 //!                      native DoclingDocument JSON (export_to_dict).
 //!   --pages A-B        convert only PDF pages A through B (1-based, inclusive;
@@ -94,6 +94,7 @@ fn main() -> ExitCode {
     let mut enrich_formula = false;
     let mut bench_warm: Option<usize> = None;
     let mut pages: Option<(usize, usize)> = None;
+    let mut ocr_lang: Option<String> = None;
     let mut path: Option<String> = None;
     let mut args = std::env::args().skip(1);
     while let Some(arg) = args.next() {
@@ -130,6 +131,20 @@ fn main() -> ExitCode {
                     return ExitCode::from(2);
                 }
             },
+            // OCR recognition language for scanned PDF/image pages: en
+            // (default; proper Latin word spacing) | ch (the multilingual
+            // docling-conformance model).
+            "--ocr-lang" => match args.next() {
+                Some(v) if matches!(v.trim(), "en" | "ch") => ocr_lang = Some(v),
+                Some(v) => {
+                    eprintln!("error: --ocr-lang {v:?} is not en|ch");
+                    return ExitCode::from(2);
+                }
+                None => {
+                    eprintln!("error: --ocr-lang needs a value (en|ch)");
+                    return ExitCode::from(2);
+                }
+            },
             // Hidden benchmarking aid: load the PDF/image pipeline once, then time
             // N warm conversions (models already loaded), printing the avg seconds
             // per conversion to stdout. This is the startup-excluded counterpart to
@@ -168,7 +183,7 @@ fn main() -> ExitCode {
     };
 
     let Some(path) = path else {
-        eprintln!("usage: docling-rs [--strict] [--to md|json] [--images MODE] [--fetch-images] [--no-stream] [--no-table-former] [--no-ocr] [--use-web-browser] <input-file>");
+        eprintln!("usage: docling-rs [--strict] [--to md|json] [--images MODE] [--fetch-images] [--no-stream] [--no-table-former] [--no-ocr] [--ocr-lang en|ch] [--use-web-browser] <input-file>");
         return ExitCode::from(2);
     };
 
@@ -214,6 +229,9 @@ fn main() -> ExitCode {
     if let Some((first, last)) = pages {
         converter = converter.page_range(first, last);
     }
+    if let Some(lang) = &ocr_lang {
+        converter = converter.ocr_lang(lang.clone());
+    }
 
     // Stream Markdown by default: print each chunk as the converter produces it
     // (page by page for PDF). Referenced images stream too (#80): each page's

crates/docling-node/README.md

@@ -294,6 +294,11 @@ for (const img of res.images) {
 
 JSON output always embeds extracted images as data URIs.
 
+For scanned PDFs/images, `ocrLang: 'en' | 'ch'` picks the OCR recognition
+model (`en` is the default — proper Latin word spacing; `ch` is the
+multilingual docling-conformance model), and `pages: 'A-B'` converts only that
+1-based PDF page window.
+
 ## API
 
 ### Functions

crates/docling-node/src/lib.rs

@@ -40,6 +40,10 @@ pub struct ConverterOptions {
     /// Convert only this PDF page window: `"A-B"` or a single page `"N"`
     /// (1-based inclusive — issue #80). Other formats ignore it.
     pub pages: Option<String>,
+    /// OCR recognition language for scanned PDF/image pages: `"en"` (default;
+    /// proper Latin word spacing) or `"ch"` (the multilingual
+    /// docling-conformance model). Formats that never OCR ignore it.
+    pub ocr_lang: Option<String>,
     /// Emit cleaner, more conformant Markdown (code-fence languages preserved,
     /// no inline-run spacing artifacts) instead of docling's byte-for-byte
     /// legacy output. Markdown only. Default `false`.
@@ -80,6 +84,8 @@ pub struct ConvertOptions {
     pub video_frames: Option<u32>,
     /// PDF page window `"A-B"` (or `"N"`), 1-based inclusive (#80).
     pub pages: Option<String>,
+    /// OCR recognition language for scanned pages: `"en"` (default) | `"ch"`.
+    pub ocr_lang: Option<String>,
     pub allowed_formats: Option<Vec<String>>,
     pub to: Option<String>,
     pub image_mode: Option<String>,
@@ -135,6 +141,7 @@ struct ConvertConfig {
     asr_model: Option<String>,
     video_frames: Option<usize>,
     page_range: Option<(usize, usize)>,
+    ocr_lang: Option<String>,
     allowed_formats: Option<Vec<InputFormat>>,
     to: OutputKind,
     image_mode: ImageMode,
@@ -193,13 +200,23 @@ fn build_config(o: ConvertOptions) -> Result<ConvertConfig> {
         asr_model: o.asr_model,
         video_frames: o.video_frames.map(|n| n as usize),
         page_range: parse_pages(o.pages.as_deref())?,
+        ocr_lang: parse_ocr_lang(o.ocr_lang)?,
         allowed_formats: allowed,
         to: parse_output_kind(o.to.as_deref())?,
         image_mode: parse_image_mode(o.image_mode.as_deref())?,
         artifacts_dir: o.artifacts_dir.unwrap_or_else(|| "artifacts".to_string()),
     })
 }
 
+/// Validate an `ocrLang` option (`"en"`/`"ch"`); an unknown id is an error.
+fn parse_ocr_lang(s: Option<String>) -> Result<Option<String>> {
+    match s {
+        Some(v) if docling::OcrLang::parse(&v).is_some() => Ok(Some(v)),
+        Some(v) => Err(Error::from_reason(format!("ocrLang {v:?} is not en|ch"))),
+        None => Ok(None),
+    }
+}
+
 /// `"A-B"` / `"N"` → the converter's 1-based inclusive page window (#80).
 fn parse_pages(s: Option<&str>) -> Result<Option<(usize, usize)>> {
     s.map(|v| docling::parse_page_range(v).map_err(|e| Error::from_reason(format!("pages: {e}"))))
@@ -219,9 +236,13 @@ fn build_converter(cfg: &ConvertConfig) -> RsConverter {
         Some(max) => base.video_frames(max),
         None => base,
     };
-    match cfg.page_range {
+    let base = match cfg.page_range {
         Some((first, last)) => base.page_range(first, last),
         None => base,
+    };
+    match &cfg.ocr_lang {
+        Some(lang) => base.ocr_lang(lang.clone()),
+        None => base,
     }
 }
 
@@ -394,6 +415,7 @@ pub struct DocumentConverter {
     asr_model: Option<String>,
     video_frames: Option<usize>,
     page_range: Option<(usize, usize)>,
+    ocr_lang: Option<String>,
     allowed_formats: Option<Vec<InputFormat>>,
 }
 
@@ -416,6 +438,7 @@ impl DocumentConverter {
             asr_model: o.asr_model.clone(),
             video_frames: o.video_frames.map(|n| n as usize),
             page_range: parse_pages(o.pages.as_deref())?,
+            ocr_lang: parse_ocr_lang(o.ocr_lang.clone())?,
             allowed_formats: allowed,
         })
     }
@@ -428,6 +451,7 @@ impl DocumentConverter {
             asr_model: self.asr_model.clone(),
             video_frames: self.video_frames,
             page_range: self.page_range,
+            ocr_lang: self.ocr_lang.clone(),
             allowed_formats: self.allowed_formats.clone(),
             to: parse_output_kind(out.to.as_deref())?,
             image_mode: parse_image_mode(out.image_mode.as_deref())?,
@@ -841,6 +865,7 @@ fn output_config(out: Option<OutputOptions>, strict: bool) -> Result<ConvertConf
         asr_model: None,
         video_frames: None,
         page_range: None,
+        ocr_lang: None,
         allowed_formats: None,
         to: parse_output_kind(out.to.as_deref())?,
         image_mode: parse_image_mode(out.image_mode.as_deref())?,

crates/docling-pdf/src/lib.rs

@@ -53,6 +53,7 @@ use docling_core::Node;
 #[cfg(feature = "ml")]
 pub use mets::{convert_mets_gbs, convert_mets_gbs_with_options};
 #[cfg(feature = "ml")]
+pub use ocr::OcrLang;
 pub use pdfium_backend::PdfDocument;
 pub use pdfium_backend::{PdfPage, TextCell};
 
@@ -346,6 +347,8 @@ struct Worker {
     /// Skip layout, OCR, and TableFormer; reconstruct text purely from the PDF's
     /// embedded text layer. See [`Pipeline::no_ocr`].
     no_ocr: bool,
+    /// Which recognition model [`Self::ocr`] loads. See [`Pipeline::ocr_lang`].
+    ocr_lang: ocr::OcrLang,
 }
 
 #[cfg(feature = "ml")]
@@ -356,6 +359,7 @@ impl Worker {
         enrich_slots: (Option<SharedClassifier>, Option<SharedCodeFormula>),
         enrich: EnrichmentOptions,
         no_ocr: bool,
+        ocr_lang: ocr::OcrLang,
     ) -> Result<Self, PdfError> {
         Ok(Self {
             layout: if no_ocr {
@@ -369,6 +373,7 @@ impl Worker {
             code_formula: enrich_slots.1,
             enrich,
             no_ocr,
+            ocr_lang,
         })
     }
 
@@ -467,7 +472,7 @@ impl Worker {
         // No text layer → recognise text from the page image via OCR.
         if page.cells.is_empty() {
             if self.ocr.is_none() {
-                self.ocr = Some(ocr::OcrModel::load().map_err(PdfError::Ocr)?);
+                self.ocr = Some(ocr::OcrModel::load(self.ocr_lang).map_err(PdfError::Ocr)?);
             }
             let cells = timing::timed("ocr.page", || {
                 self.ocr
@@ -715,6 +720,8 @@ pub struct Pipeline {
     enrich: EnrichmentOptions,
     /// 1-based inclusive page window to convert. See [`Pipeline::pages`].
     page_range: Option<(usize, usize)>,
+    /// OCR recognition language. See [`Pipeline::ocr_lang`].
+    ocr_lang: ocr::OcrLang,
 }
 
 #[cfg(feature = "ml")]
@@ -735,6 +742,7 @@ impl Pipeline {
             no_ocr: false,
             enrich: EnrichmentOptions::default(),
             page_range: None,
+            ocr_lang: ocr::OcrLang::from_env(),
         })
     }
 
@@ -757,6 +765,32 @@ impl Pipeline {
         self.page_range = range;
     }
 
+    /// OCR recognition language (see [`OcrLang`]): English by default, `ch`
+    /// for the multilingual docling-conformance model. `None` keeps the
+    /// process default (`DOCLING_RS_OCR_LANG`, else English). Set before the
+    /// first conversion; for a warm pipeline use
+    /// [`set_ocr_lang`](Self::set_ocr_lang).
+    pub fn ocr_lang(mut self, lang: Option<ocr::OcrLang>) -> Self {
+        self.set_ocr_lang(lang);
+        self
+    }
+
+    /// In-place variant of [`ocr_lang`](Self::ocr_lang) for a long-lived
+    /// pipeline (docling-serve's warm instance). Unlike the page window this
+    /// is a *model* switch: any worker whose cached recognition model was
+    /// loaded for a different language drops it, to be lazily reloaded on the
+    /// next OCR-needing page (cheap — the rec models are ~10 MB).
+    pub fn set_ocr_lang(&mut self, lang: Option<ocr::OcrLang>) {
+        let lang = lang.unwrap_or_else(ocr::OcrLang::from_env);
+        self.ocr_lang = lang;
+        for worker in self.primary.iter_mut().chain(self.pool.iter_mut()) {
+            if worker.ocr_lang != lang {
+                worker.ocr_lang = lang;
+                worker.ocr = None;
+            }
+        }
+    }
+
     /// Resolve the configured 1-based window against a page count into the
     /// 0-based inclusive form the backend walks, validating it selects at
     /// least one existing page.
@@ -854,6 +888,7 @@ impl Pipeline {
                 self.enrich_slots(),
                 self.enrich,
                 self.no_ocr,
+                self.ocr_lang,
             )?);
         }
         Ok(self.primary.as_mut().unwrap())
@@ -1218,6 +1253,7 @@ impl Pipeline {
         }
         let intra = pdf_intra();
         let no_ocr = self.no_ocr;
+        let ocr_lang = self.ocr_lang;
         let enrich = self.enrich;
         let tables = self.tables_slot();
         let enrich_slots = self.enrich_slots();
@@ -1226,7 +1262,9 @@ impl Pipeline {
                 .map(|_| {
                     let tables = tables.clone();
                     let enrich_slots = enrich_slots.clone();
-                    s.spawn(move || Worker::load(intra, tables, enrich_slots, enrich, no_ocr))
+                    s.spawn(move || {
+                        Worker::load(intra, tables, enrich_slots, enrich, no_ocr, ocr_lang)
+                    })
                 })
                 .collect();
             handles.into_iter().map(|h| h.join().unwrap()).collect()
@@ -1292,6 +1330,7 @@ pub fn convert(
         false,
         EnrichmentOptions::default(),
         None,
+        None,
     )
 }
 
@@ -1300,6 +1339,10 @@ pub fn convert(
 /// [`Pipeline::no_table_former`]) and/or layout+OCR+TableFormer entirely (see
 /// [`Pipeline::no_ocr`]), and/or enables the enrichment passes (see
 /// [`Pipeline::enrichments`]).
+// One positional per pipeline switch mirrors the Pipeline builder; growing
+// past clippy's arity cap is the price of keeping this one-shot signature
+// stable-ish instead of churning callers into an options struct mid-series.
+#[allow(clippy::too_many_arguments)]
 pub fn convert_with_options(
     bytes: &[u8],
     password: Option<&str>,
@@ -1308,19 +1351,28 @@ pub fn convert_with_options(
     no_ocr: bool,
     enrich: EnrichmentOptions,
     pages: Option<(usize, usize)>,
+    ocr_lang: Option<OcrLang>,
 ) -> Result<DoclingDocument, PdfError> {
     Pipeline::new()?
         .no_table_former(no_table_former)
         .no_ocr(no_ocr)
         .enrichments(enrich)
         .pages(pages)
+        .ocr_lang(ocr_lang)
         .convert(bytes, password, name)
 }
 
 #[cfg(feature = "ml")]
 /// Convenience one-shot image conversion (loads the pipeline per call).
 pub fn convert_image(bytes: &[u8], name: &str) -> Result<DoclingDocument, PdfError> {
-    convert_image_with_options(bytes, name, false, false, EnrichmentOptions::default())
+    convert_image_with_options(
+        bytes,
+        name,
+        false,
+        false,
+        EnrichmentOptions::default(),
+        None,
+    )
 }
 
 #[cfg(feature = "ml")]
@@ -1333,11 +1385,13 @@ pub fn convert_image_with_options(
     no_table_former: bool,
     no_ocr: bool,
     enrich: EnrichmentOptions,
+    ocr_lang: Option<OcrLang>,
 ) -> Result<DoclingDocument, PdfError> {
     Pipeline::new()?
         .no_table_former(no_table_former)
         .no_ocr(no_ocr)
         .enrichments(enrich)
+        .ocr_lang(ocr_lang)
         .convert_image(bytes, name)
 }