Dart PDF Translator

A versatile command-line tool to extract text from PDF files and translate it page by page using either the Google Gemini API or a local Ollama instance.

This tool is designed for developers who need to automate the translation of PDF documents directly from the terminal.

Features

  • PDF Text Extraction: Reliably extracts text from PDF files using the battle-tested Poppler command-line tools.
  • Flexible Translation Engines: Choose between:
    • Gemini: Google's powerful and scalable translation models.
    • Ollama: Run translations locally using your own models (e.g., Llama3, Mistral) for privacy and offline use.
  • Page-by-Page Processing: Translates large documents page by page to avoid API context limits and provide incremental progress.
  • Markdown Output: Saves the translated content in a clean, structured Markdown file.
  • Configurable: Easily configure your translation engine, API keys, and models via an .env file.
  • Pub.dev Ready: Structured and documented to be published as a reusable package.

Prerequisites

  1. Dart SDK: Make sure you have the Dart SDK installed.

  2. Poppler (for PDF extraction): The command-line tools pdftotext and pdfinfo are required for PDF processing on desktop/CLI.

    • macOS (via Homebrew):

      brew install poppler

    • Windows (via Winget - Recommended):

      winget install poppler

    • Linux (Debian/Ubuntu):

      sudo apt-get update && sudo apt-get install poppler-utils

    Important:

    • After installing, ensure the tools are available in your system's PATH. You can test by running pdftotext -v and pdfinfo -v in your terminal.
    • If you want to use a different PDF processor (e.g., for Flutter/mobile), you can implement your own PdfProcessorStrategy.

Setup

  1. Clone the repository or download the source code.

  2. Configure your environment (.env):

    • Copy .env.example to .env.
    • Edit the .env file and fill in the values according to your desired translation engine.
    # ---------------------------
# GENERAL SETTINGS
# ---------------------------
# The translation engine to use. Options: "gemini" or "ollama".
TRANSLATION_ENGINE=gemini

# The language to translate the PDF text into (e.g., "English", "Portuguese").
TARGET_LANGUAGE=English

# ---------------------------
# GEMINI SETTINGS
# ---------------------------
# Required if TRANSLATION_ENGINE is "gemini".
GEMINI_API_KEY=YOUR_API_KEY_HERE
GEMINI_MODEL=gemini-2.5-flash

# ---------------------------
# OLLAMA SETTINGS
# ---------------------------
# Required if TRANSLATION_ENGINE is "ollama".
OLLAMA_API_URL=http://localhost:11434
OLLAMA_MODEL=llama3

    Tips:

    • To use Gemini, get your API key at aistudio.google.com/app/apikey
    • To use Ollama, make sure the model is available locally (e.g., ollama pull llama3)
    • The engine is selected via TRANSLATION_ENGINE in your .env file.

  3. Install dependencies:

    dart pub get

Usage

  1. Place a PDF file in the project directory (e.g., sample.pdf).

  2. Run the translator from your terminal, passing the PDF path if you want: sh # Using the default 'sample.pdf' dart run bin/translator.dart # Specifying another PDF file dart run bin/translator.dart path/to/my_document.pdf

  3. A new Markdown file (e.g., my_document_translated.md) will be created with the translated content.

Using with different processors and translators

  • PDF processing is done via strategies (Strategy Pattern). By default, Poppler (CLI) is used. For Flutter/mobile, implement your own strategy.
  • Translation is performed by classes implementing the Translator interface. The engine is selected automatically via .env.
  • For programmatic usage, see the example below:
import 'package:ai_dart_pdf_translator/ai_dart_pdf_translator.dart';

void main() async {
    final processor = PopplerPdfProcessor();
    final pages = await processor.extractText('my.pdf');

    final translator = GeminiTranslator('YOUR_API_KEY');
    final translated = await translator.translate(text: pages[0], targetLanguage: 'Portuguese');
    print(translated);
}

Flutter Example App

This project includes a complete Flutter application in the example/ directory to demonstrate how the translation logic can be used within a mobile/desktop UI.

Note: The example app uses a Flutter-compatible package (syncfusion_flutter_pdf) for text extraction, as the command-line Poppler tools are not suitable for a mobile environment. This showcases how the core Translator interface can be used with different platform-specific utilities.

Running the Example

  1. Set up the API Key: Ensure you have a valid GEMINI_API_KEY in the main .env file at the root of this project (ai_dart_pdf_translator/.env). The example app is configured to read the key from there.

  2. Navigate to the example directory:

    cd example

  3. Run the Flutter app:

    flutter run

  4. Use the "Pick PDF" button in the app to select a file and start the translation.

Library vs. Executable

This package can be used both as a CLI executable and as a library. The main components are exported for programmatic use. See the example/ directory for usage examples.

Publishing to Pub.dev

This package is ready to be published on pub.dev.

  1. Update the homepage and repository fields in pubspec.yaml.
  2. Review the LICENSE, CHANGELOG.md, and documentation.
  3. Run dart pub publish --dry-run to validate the package.
  4. If everything is OK, publish with dart pub publish

Libraries

ai_dart_pdf_translator
A versatile command-line PDF translator.