### Install BabelDOC from Source using uv

Source: https://github.com/funstory-ai/babeldoc/blob/main/README.md

Clones the BabelDOC repository and installs it from source using uv. Ensure uv is installed and its PATH is set up.

```bash
# clone the project
git clone https://github.com/funstory-ai/BabelDOC

# enter the project directory
cd BabelDOC

# install dependencies and run babeldoc
uv run babeldoc --help
```

--------------------------------

### Install BabelDOC from PyPI using uv

Source: https://github.com/funstory-ai/babeldoc/blob/main/README.md

Installs BabelDOC using the uv tool. Ensure uv is installed and its PATH is set up.

```bash
uv tool install --python 3.12 BabelDOC

babeldoc --help
```

--------------------------------

### PDF Name Example

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/intro-to-pdf-object.md

Names are keywords or dictionary keys starting with a forward slash.

```pdf
/Type
```

--------------------------------

### Conventional Commits Example

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/CONTRIBUTING.md

Commit messages should follow the Conventional Commits specification. An example is provided for feature commits.

```bash
feat(translator): add openai.
```

--------------------------------

### Python Docstring Example (Google Style)

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/CONTRIBUTING.md

Public functions and classes must have docstrings using the Google style, including Args, Returns, and Raises sections.

```python
def function_name(arg1: str, arg2: int) -> bool:
    """Short description of function.

    Args:
        arg1: Description of arg1
        arg2: Description of arg2

    Returns:
        Description of return value

    Raises:
        ValueError: Description of when this error occurs
    """
```

--------------------------------

### Example PDF File Structure

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/intro-to-pdf-object.md

This snippet illustrates the typical structure of a PDF file, including object definitions, a cross-reference table, and trailer information. It demonstrates how different objects are defined and referenced within the document.

```pdf
%PDF-2.0
1 0 obj
<<
  /Pages 2 0 R
  /Type /Catalog
>>
endobj
2 0 obj
<<
  /Count 1
  /Kids [
    3 0 R
  ]
  /Type /Pages
>>
endobj
3 0 obj
<<
  /Contents 4 0 R
  /MediaBox [ 0 0 612 792 ]
  /Parent 2 0 R
  /Resources <<
    /Font << /F1 5 0 R >>
  >>
  /Type /Page
>>
endobj
4 0 obj
<<
  /Length 44
>>
stream
BT
  /F1 24 Tf
  72 720 Td
  (Potato) Tj
ET
endstream
endobj
5 0 obj
<<
  /BaseFont /Helvetica
  /Encoding /WinAnsiEncoding
  /Subtype /Type1
  /Type /Font
>>
endobj

xref
0 6
0000000000 65535 f 
0000000009 00000 n 
0000000062 00000 n 
0000000133 00000 n 
0000000277 00000 n 
0000000372 00000 n 
trailer <<
  /Root 1 0 R
  /Size 6
  /ID [<42841c13bbf709d79a200fa1691836f8><b1d8b5838eeafe16125317aa78e666aa>]
>>
startxref
478
%%EOF

```

--------------------------------

### Python Type Hinting Example

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/CONTRIBUTING.md

Use type hints for function arguments and return values to improve code readability and maintainability.

```python
def translate_text(text: str) -> str:
```

--------------------------------

### Progress Start Event Structure

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/ImplementationDetails/AsyncTranslate/AsyncTranslate.md

This event is emitted when a translation stage begins. It provides details about the current stage and its total items.

```python
{
    "type": "progress_start",
    "stage": str,              # Name of the current stage
    "stage_progress": float,   # Always 0.0
    "stage_current": int,      # Current progress count (0)
    "stage_total": int         # Total items to process in this stage
}
```

--------------------------------

### BabelDOC TOML Configuration Example

Source: https://github.com/funstory-ai/babeldoc/blob/main/README.md

This TOML configuration file sets various parameters for BabelDOC, including debugging, language settings, output paths, PDF processing options, and translation service details like OpenAI model and API key.

```toml
[babeldoc]
# Basic settings
debug = true
lang-in = "en-US"
lang-out = "zh-CN"
qps = 10
output = "/path/to/output/dir"

# PDF processing options
split-short-lines = false
short-line-split-factor = 0.8
skip-clean = false
dual-translate-first = false
disable-rich-text-translate = false
use-alternating-pages-dual = false
watermark-output-mode = "watermarked"  # Choices: "watermarked", "no_watermark", "both"
max-pages-per-part = 50  # Automatically split the document for translation and merge it back.
only_include_translated_page = false # Only include translated pages in the output PDF. Effective only when `pages` is used.
# no-watermark = false  # DEPRECATED: Use watermark-output-mode instead
skip-scanned-detection = false  # Skip scanned document detection for faster processing
auto_extract_glossary = true # Set to false to disable automatic term extraction
formular_font_pattern = "" # Font pattern for formula text
formular_char_pattern = "" # Character pattern for formula text
show_char_box = false # Show character bounding boxes (debug)
ocr_workaround = false # Use OCR workaround for scanned PDFs
rpc_doclayout = "" # RPC service host for document layout analysis
working_dir = "" # Working directory for translation
auto_enable_ocr_workaround = false # Enable automatic OCR workaround for scanned PDFs. See docs for interaction with ocr_workaround and skip_scanned_detection.
skip_form_render = false # Skip form rendering (default: False)
skip_curve_render = false # Skip curve rendering (default: False)
only_parse_generate_pdf = false # Only parse PDF and generate output PDF without translation (default: False)
remove_non_formula_lines = false # Remove non-formula lines from paragraph areas (default: False)
non_formula_line_iou_threshold = 0.2 # IoU threshold for paragraph overlap detection (default: 0.2)
figure_table_protection_threshold = 0.3 # IoU threshold for figure/table protection (default: 0.3)

# Translation service
openai = true
openai-model = "gpt-4o-mini"
openai-base-url = "https://api.openai.com/v1"
openai-api-key = "your-api-key-here"
enable-json-mode-if-requested = false  # Enable JSON mode when requested (default: false)
disable_same_text_fallback = false # Disable fallback translation when LLM output matches input text (default: false)
pool-max-workers = 8  # Maximum worker threads for task processing (defaults to QPS value if not set)

# Glossary Options (Optional)
# glossary-files = "/path/to/glossary1.csv,/path/to/glossary2.csv"

# Output control
no-dual = false
no-mono = false
min-text-length = 5
report-interval = 0.5

# Offline assets management
# Uncomment one of these options as needed:
# generate-offline-assets = "/path/to/output/dir"
# restore-offline-assets = "/path/to/offline_assets_package.zip"

```

--------------------------------

### PDF Null Example

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/intro-to-pdf-object.md

The null object is represented by the keyword 'null'.

```pdf
null
```

--------------------------------

### PDF Number Examples

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/intro-to-pdf-object.md

Numbers can be integers or floating-point values. They are often interchangeable in practice.

```pdf
12
```

```pdf
3.14159
```

--------------------------------

### PDF Dictionary Example

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/intro-to-pdf-object.md

Dictionaries are collections of key-value pairs enclosed in << and >>. Keys are Names and values can be any object type.

```pdf
<< /A 1 /B [2, 3 <</Four 4>> ] >>
```

--------------------------------

### Async Translation Usage

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/ImplementationDetails/AsyncTranslate/AsyncTranslate.md

Example of how to use the async_translate function to translate a PDF file and handle progress updates, completion, and errors.

```APIDOC
## Async Translation Usage

### Description
This code snippet demonstrates how to use the `async_translate` function to perform asynchronous translation of a PDF file. It shows how to configure the translation, iterate over progress events, and handle different event types such as progress updates, completion, and errors.

### Method
Asynchronous Function Call

### Endpoint
N/A (This is a Python function)

### Parameters
This function does not have traditional API parameters. Configuration is passed via a `TranslationConfig` object.

### Request Example
```python
async def translate_with_progress():
    config = TranslationConfig(
        input_file="example.pdf",
        translator=your_translator,
        # ... other configuration options
    )
    
    try:
        async for event in async_translate(config):
            if event["type"] == "progress_update":
                print(f"Progress: {event['overall_progress']}")
            elif event["type"] == "finish":
                result = event["translate_result"]
                print(f"Translation completed: {result.original_pdf_path}")
            elif event["type"] == "error":
                print(f"Error occurred: {event['error']}")
                break
    except asyncio.CancelledError:
        print("Translation was cancelled")
    except KeyboardInterrupt:
        print("Translation was interrupted")
```

### Response
This function yields event dictionaries. The structure of these dictionaries depends on the `event['type']`.

#### Event Types:

- **progress_start**:
  ```json
  {
      "type": "progress_start",
      "stage": "string",
      "stage_progress": 0.0,
      "stage_current": 0,
      "stage_total": "integer"
  }
  ```

- **progress_update**:
  ```json
  {
      "type": "progress_update",
      "stage": "string",
      "stage_progress": "float (0-100)",
      "stage_current": "integer",
      "stage_total": "integer",
      "overall_progress": "float (0-100)"
  }
  ```

- **progress_end**:
  ```json
  {
      "type": "progress_end",
      "stage": "string",
      "stage_progress": 100.0,
      "stage_current": "integer",
      "stage_total": "integer",
      "overall_progress": "float (0-100)"
  }
  ```

- **finish**:
  ```json
  {
      "type": "finish",
      "translate_result": "TranslateResult object"
  }
  ```

- **error**:
  ```json
  {
      "type": "error",
      "error": "string"
  }
  ```

### Response Example (Progress Update)
```json
{
  "type": "progress_update",
  "stage": "LayoutParser",
  "stage_progress": 50.5,
  "stage_current": 50,
  "stage_total": 100,
  "overall_progress": 25.0
}
```
```

--------------------------------

### PDF Array Example

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/intro-to-pdf-object.md

Arrays are ordered collections of objects enclosed in square brackets. They support nested structures.

```pdf
[1 (two) 3.14 false]
```

--------------------------------

### PDF Stream Example

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/intro-to-pdf-object.md

Streams contain binary data, structured as a dictionary followed by the stream content between 'stream' and 'endstream'. The /Length key in the dictionary specifies the stream's byte count.

```pdf
stream
...binary data...
endstream
```

--------------------------------

### PDF String Example

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/intro-to-pdf-object.md

Strings are text sequences enclosed in parentheses. They typically do not support full Unicode encoding.

```pdf
(potato)
```

--------------------------------

### PDF Boolean Example

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/intro-to-pdf-object.md

Boolean values are represented by true or false.

```pdf
true
```

```pdf
false
```

--------------------------------

### PDF Object Definition Example

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/intro-to-pdf-object.md

PDF objects at the top level are identified by an object number, a generation number, and the 'obj' and 'endobj' keywords.

```pdf
1 0 obj
...object body...
endobj
```

--------------------------------

### PDF Indirect Object Reference Example

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/intro-to-pdf-object.md

An indirect object reference points to a numbered object in the file using its object and generation numbers.

```pdf
1 0 R
```

--------------------------------

### Run Development and Testing

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/CONTRIBUTING.md

Use this command for development and testing within the project. It ensures the correct environment is used.

```bash
uv run BabelDOC
```

--------------------------------

### Add New Dependencies

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/CONTRIBUTING.md

It is recommended to use the `uv add` command for adding new dependencies to the project. This ensures proper management of project dependencies.

```bash
uv add
```

--------------------------------

### Translate multiple PDF files from source using uv run

Source: https://github.com/funstory-ai/babeldoc/blob/main/README.md

Translates multiple PDF files using 'uv run babeldoc' with OpenAI API configuration. Replace 'your-api-key-here' with your actual key.

```bash
uv run babeldoc --files example.pdf --files example2.pdf --openai --openai-model "gpt-4o-mini" --openai-base-url "https://api.openai.com/v1" --openai-api-key "your-api-key-here"
```

--------------------------------

### Logging in Development

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/CONTRIBUTING.md

When logging information during development, use `log.debug()` for detailed output. Avoid using the standard `print()` function.

```python
log.debug()
```

--------------------------------

### Translate a single PDF file from source using uv run

Source: https://github.com/funstory-ai/babeldoc/blob/main/README.md

Translates a single PDF file using 'uv run babeldoc' with OpenAI API configuration. Replace 'your-api-key-here' with your actual key.

```bash
uv run babeldoc --files example.pdf --openai --openai-model "gpt-4o-mini" --openai-base-url "https://api.openai.com/v1" --openai-api-key "your-api-key-here"
```

--------------------------------

### Generate Offline Assets Package

Source: https://github.com/funstory-ai/babeldoc/blob/main/README.md

Use this command to create a zip archive containing all necessary models and fonts for offline use. Specify the output directory where the package will be saved.

```bash
babeldoc --generate-offline-assets /path/to/output/dir
```

--------------------------------

### Translate multiple PDF files using BabelDOC CLI

Source: https://github.com/funstory-ai/babeldoc/blob/main/README.md

Translates multiple PDF files using the babeldoc command with OpenAI API configuration. Replace 'your-api-key-here' with your actual key.

```bash
babeldoc --openai --openai-model "gpt-4o-mini" --openai-base-url "https://api.openai.com/v1" --openai-api-key "your-api-key-here"  --files example1.pdf --files example2.pdf
```

--------------------------------

### Profile Memory Usage

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/CONTRIBUTING.md

Use `uv run memray run` to profile memory usage of the Python script. Include native and aggregate options for detailed analysis.

```bash
uv run memray run --native --aggregate babeldoc/main.py -c babeldoc.toml
```

--------------------------------

### Generate Python Classes from XSD

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/CONTRIBUTING.md

Use the `xsdata` command to generate Python classes from an XSD schema. Specify the output package.

```bash
xsdata generate babeldoc/format/pdf/document_il/il_version_1.xsd --package babeldoc.format.pdf.document_il
```

--------------------------------

### Translate a single PDF file using BabelDOC CLI

Source: https://github.com/funstory-ai/babeldoc/blob/main/README.md

Translates a single PDF file using the babeldoc command with OpenAI API configuration. Replace 'your-api-key-here' with your actual key.

```bash
babeldoc --openai --openai-model "gpt-4o-mini" --openai-base-url "https://api.openai.com/v1" --openai-api-key "your-api-key-here"  --files example.pdf
```

--------------------------------

### Generate CMap Resources (Windows)

Source: https://github.com/funstory-ai/babeldoc/blob/main/babeldoc/format/pdf/new_parser/runtime/data/cmap/README.txt

Commands for generating CMap resources on Windows systems without the `make` command. It involves creating a directory and running `conv_cmap.py` with specific encoding mappings for different CJK languages.

```bash
mkdir pdfminer\cmap
python tools\conv_cmap.py -c B5=cp950 -c UniCNS-UTF8=utf-8 pdfminer\cmap Adobe-CNS1 cmaprsrc\cid2code_Adobe_CNS1.txt
python tools\conv_cmap.py -c GBK-EUC=cp936 -c UniGB-UTF8=utf-8 pdfminer\cmap Adobe-GB1 cmaprsrc\cid2code_Adobe_GB1.txt
python tools\conv_cmap.py -c RKSJ=cp932 -c EUC=euc-jp -c UniJIS-UTF8=utf-8 pdfminer\cmap Adobe-Japan1 cmaprsrc\cid2code_Adobe_Japan1.txt
python tools\conv_cmap.py -c KSC-EUC=euc-kr -c KSC-Johab=johab -c KSCms-UHC=cp949 -c UniKS-UTF8=utf-8 pdfminer\cmap Adobe-Korea1 cmaprsrc\cid2code_Adobe_Korea1.txt
```

--------------------------------

### Python String Formatting with f-strings

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/CONTRIBUTING.md

Prefer f-strings for string formatting for clarity and conciseness.

```python
f"Count: {count}"
```

--------------------------------

### Generate XSD from RNC

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/CONTRIBUTING.md

Use the `trang` command to generate an XSD schema from an RNC schema.

```bash
trang babeldoc/format/pdf/document_il/il_version_1.rnc babeldoc/format/pdf/document_il/il_version_1.xsd
```

--------------------------------

### Translate PDF Asynchronously with Progress

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/ImplementationDetails/AsyncTranslate/AsyncTranslate.md

Use this function to translate PDF files asynchronously. It yields progress events that can be used to update UI elements. Handle potential cancellation or interruption errors.

```python
async def translate_with_progress():
    config = TranslationConfig(
        input_file="example.pdf",
        translator=your_translator,
        # ... other configuration options
    )
    
    try:
        async for event in async_translate(config):
            if event["type"] == "progress_update":
                print(f"Progress: {event['overall_progress']}")
            elif event["type"] == "finish":
                result = event["translate_result"]
                print(f"Translation completed: {result.original_pdf_path}")
            elif event["type"] == "error":
                print(f"Error occurred: {event['error']}")
                break
    except asyncio.CancelledError:
        print("Translation was cancelled")
    except KeyboardInterrupt:
        print("Translation was interrupted")
```

--------------------------------

### Restore Offline Assets Package

Source: https://github.com/funstory-ai/babeldoc/blob/main/README.md

Use this command to extract models and fonts from a previously generated offline assets package. You can provide a specific zip file path or a directory containing the package.

```bash
babeldoc --restore-offline-assets /path/to/offline_assets_*.zip
```

--------------------------------

### Generate CMap Resources (Unix-like)

Source: https://github.com/funstory-ai/babeldoc/blob/main/babeldoc/format/pdf/new_parser/runtime/data/cmap/README.txt

Command to generate CMap resources using `make cmap` and `conv_cmap.py` on Unix-like systems. This process converts Adobe CMap resources into a usable format.

```bash
make cmap
python tools/conv_cmap.py pdfminer/cmap Adobe-CNS1 cmaprsrc/cid2code_Adobe_CNS1.txt
reading 'cmaprsrc/cid2code_Adobe_CNS1.txt'...
writing 'CNS1_H.py'...
...
```

--------------------------------

### Python Import Style

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/CONTRIBUTING.md

Imports should be placed on separate lines and grouped according to standard library, third-party, and local imports.

```python
import os
import sys
```

--------------------------------

### Format RNC File

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/CONTRIBUTING.md

Use the `trang` command to format the RNC file. This command is used for schema transformation.

```bash
trang babeldoc/format/pdf/document_il/il_version_1.rnc babeldoc/format/pdf/document_il/il_version_1.rnc
```

--------------------------------

### Programmatic Translation Cancellation

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/ImplementationDetails/AsyncTranslate/AsyncTranslate.md

Use this pattern to initiate a translation and then cancel it based on a condition. Ensure you await the translation task after cancellation to allow for cleanup.

```python
async def translate_with_cancellation():
    config = TranslationConfig(
        input_file="example.pdf",
        translator=your_translator,
        # ... other configuration options
    )
    
    try:
        # Start translation in another task
        translation_task = asyncio.create_task(process_translation(config))
        
        # Simulate some condition that requires cancellation
        await asyncio.sleep(5)
        config.cancel_translation()  # This will trigger cancellation
        
        await translation_task  # Wait for the task to finish
    except asyncio.CancelledError:
        print("Translation was cancelled")

async def process_translation(config):
    async for event in async_translate(config):
        if event["type"] == "error":
            if isinstance(event["error"], asyncio.CancelledError):
                print("Translation was cancelled")
                break
            print(f"Error occurred: {event['error']}")
            break
        # ... handle other events ...

```

--------------------------------

### Python Class Naming Convention

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/CONTRIBUTING.md

Class names should follow the CapWords (PascalCase) convention.

```python
class TranslatorConfig
```

--------------------------------

### Python Private Attribute Naming Convention

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/CONTRIBUTING.md

Private attributes should be prefixed with an underscore.

```python
_internal_state
```

--------------------------------

### Finish Event Structure

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/ImplementationDetails/AsyncTranslate/AsyncTranslate.md

Emitted upon successful completion of the entire translation process. It contains the result object with paths to translated files.

```python
{
    "type": "finish",
    "translate_result": TranslateResult  # Contains paths to translated files and timing info
}
```

--------------------------------

### Commit Changes to New Branch

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/CONTRIBUTING.md

Stage all changes and commit them with a semantic message. This is a standard Git workflow for tracking changes.

```bash
git add .

git commit -m "<semantic commit message>"
```

--------------------------------

### Progress Update Event Structure

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/ImplementationDetails/AsyncTranslate/AsyncTranslate.md

Emitted periodically during translation, this event details the progress within the current stage and the overall translation progress.

```python
{
    "type": "progress_update",
    "stage": str,              # Name of the current stage
    "stage_progress": float,   # Progress percentage of current stage (0-100)
    "stage_current": int,      # Current items processed in this stage
    "stage_total": int,        # Total items to process in this stage
    "overall_progress": float  # Overall translation progress (0-100)
}
```

--------------------------------

### Progress End Event Structure

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/ImplementationDetails/AsyncTranslate/AsyncTranslate.md

This event signifies the completion of a translation stage, indicating 100% progress for that stage.

```python
{
    "type": "progress_end",
    "stage": str,              # Name of the completed stage
    "stage_progress": float,   # Always 100.0
    "stage_current": int,      # Equal to stage_total
    "stage_total": int,        # Total items processed in this stage
    "overall_progress": float  # Overall translation progress (0-100)
}
```

--------------------------------

### Generate RNG from RNC

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/CONTRIBUTING.md

Use the `trang` command to generate an RNG schema from an RNC schema.

```bash
trang babeldoc/format/pdf/document_il/il_version_1.rnc babeldoc/format/pdf/document_il/il_version_1.rng
```

--------------------------------

### Python Constant Naming Convention

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/CONTRIBUTING.md

Constants should be named using UPPER_CASE.

```python
MAX_RETRY_COUNT = 3
```

--------------------------------

### Python Function and Variable Naming Convention

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/CONTRIBUTING.md

Function and variable names should use the snake_case convention.

```python
def process_text()
```

```python
word_count = 0
```

--------------------------------

### Error Event Structure

Source: https://github.com/funstory-ai/babeldoc/blob/main/docs/ImplementationDetails/AsyncTranslate/AsyncTranslate.md

This event is emitted if any error occurs during the translation process, providing an error message.

```python
{
    "type": "error",
    "error": str  # Error message
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.