InsituTranslate

English | 简体中文

This project is still under development, and many features are not yet complete.

InsituTranslate is a local desktop document translation tool built with Tauri 2, React, TypeScript, and Rust.

The core objective of the project is to preserve the original file’s formatting, structure, styles, and non-textual data as much as possible while translating its content, and then write the translated text back into the corresponding format.

Current version: 0.1.0
Project status: Under development
Primary development platform: Windows

Features

Multi-format Document Translation

The following formats can currently be imported:

Format	Current Processing Method
PDF	Parsed locally with pdf_oxide or converted to Markdown through MinerU; currently exported as Markdown
Markdown	Translates text while preserving Markdown structures such as headings, lists, links, and emphasis
EPUB	Parses internal HTML/XHTML pages and repackages them after translation
HTML / HTM	Translates document text while preserving tags and page structure
TXT	Performs direct plain-text translation
DOCX	Modifies targeted Word XML text nodes while preserving styles, relationships, media, and document structure as much as possible
XLSX	Currently translates shared strings in sharedStrings.xml without modifying worksheet formulas or layout
JSON	Translates textual content while preserving the JSON data structure
SRT	Preserves subtitle indices and timelines while translating only subtitle text
ASS	Preserves style headers, timing information, and event properties
LRC	Preserves lyric timestamps while translating only lyric text

Multiple files can be added in a single batch. Each file is created as an independent translation task.

Translation Providers

The backend currently supports the following protocols:

• OpenAI Chat Completions
• OpenAI Responses
• Anthropic Messages
• Gemini API
• Google Vertex AI
• Ollama Chat
• OpenAI-compatible APIs and custom Base URLs
• MinerU PDF parsing services

API keys, service accounts, and custom request headers are handled by the Rust backend. They should not be written into frontend source code or committed to the Git repository.

Translation Task Management

• Create and manage translation tasks in batches
• Start, pause, resume, and retranslate tasks
• View parsing, chunking, translation, and restoration progress in real time
• Configure maximum concurrency, retry attempts, and failure percentage thresholds
• Dynamic request-rate and token-rate limiting
• Search tasks by name, tag, language, or model
• Edit task names and tags
• Import and export .inp task files
• Export completed tasks to their corresponding document formats

Translation Configuration

• Automatic source language detection or manual selection
• Target language selection
• Custom token count per chunk
• Context modes including no context, serial sliding window, parallel sliding window, and global background context
• Model reasoning effort configuration
• Model web search configuration
• Custom model request parameters
• Rule-based proofreading and translation confidence detection configuration

Glossaries

• Import CSV or JSON glossaries
• Manage, search, sort, and browse glossary entries with pagination
• Create, edit, and delete glossary entries
• Export as CSV or JSON
• Apply existing glossaries to translation tasks
• Automatically generate task glossaries using a model
• Configure an independent model, concurrency limit, retry count, and failure threshold for automatic glossary generation

CSV glossaries must contain only the following two columns:

src,dst
source term,target term

JSON glossaries use a structure similar to the following:

[
  {
    "src": "source term",
    "dst": "target term"
  }
]

Other Features

• Custom translation assistants and system prompts
• Custom assistant request parameters
• Light, dark, and system color modes
• Built-in themes and custom theme colors
• System font selection
• Backend logging and a real-time PowerShell log console

Current Development Status

InsituTranslate is still under development, and some features have not yet been completed:

• PDF text can be extracted and translated, but reconstruction into the original PDF format has not yet been implemented. PDF tasks are currently exported as Markdown.
• The proofreading page currently displays source and translated text in task chunk order. An editable proofreading interface and formatted preview have not yet been implemented.
• Installer generation is currently disabled. bundle.active is set to false in the Tauri configuration.
• DOCX, XLSX, and EPUB files generated by different applications or file generators may have compatibility differences.
• XLSX processing currently supports only shared strings. Text stored as inline strings or through other storage methods may not be translated.
• Project APIs and the .inp task format may continue to change during future development.

The current version is not recommended for irreplaceable or unrecoverable files. Always keep a backup of the original file.

Technology Stack

Frontend

• React
• TypeScript
• Vite
• Tailwind CSS
• shadcn/ui-style components
• Radix UI
• Motion
• Lucide React

Backend

• Tauri 2
• Rust
• Tokio
• SQLite / SQLx
• Reqwest
• docx-rs
• calamine
• pdf_oxide
• lib-epub
• quick-xml

Development Environment Requirements

The current repository configuration is primarily intended for Windows.

Recommended software:

• Git
• Node.js 24 or a compatible version
• pnpm 10.12.1
• Rust stable toolchain
• Microsoft Visual Studio 2022 Build Tools
• Windows SDK
• Microsoft Edge WebView2 Runtime
• PowerShell 7

When installing Visual Studio Build Tools, select:

• Desktop development with C++
• MSVC C++ Build Tools
• Windows 10 or Windows 11 SDK

Installing Rust through rustup is recommended:

winget install Rustlang.Rustup

After installation, reopen PowerShell and verify the installation:

rustc --version
cargo --version

Install pnpm:

corepack enable
corepack prepare pnpm@10.12.1 --activate

If the current Node.js environment does not include Corepack, you can use:

npm install --global pnpm@10.12.1

Clone and Run

1. Clone the Repository

git clone https://github.com/Floratina/InsituTranslate.git
Set-Location InsituTranslate

2. Check the Development Environment

node --version
pnpm --version
rustc --version
cargo --version

3. Install Frontend Dependencies

Installing according to the lockfile is recommended:

pnpm install --frozen-lockfile

If you are actively updating dependencies, use:

pnpm install

4. Start the Desktop Development Environment

pnpm tauri dev

During the first launch, Cargo needs to download and compile Rust dependencies, so it will take noticeably longer than subsequent launches.

To start only the Vite frontend, use:

pnpm dev

However, the browser environment cannot fully access file selection, databases, translation tasks, or other Tauri backend features. Full development should use pnpm tauri dev.

Configuration After First Launch

1. Add a Translation Provider

Open the “Providers” page:

1. Add a provider.
2. Select the corresponding protocol.
3. Enter the Base URL.
4. Set the API Key within the application.
5. Fetch remote models or add a model manually.
6. Use the connectivity test to confirm that the model is available.
7. Enable the providers and models you want to use.

For OpenAI-compatible services, select OpenAI Chat Completions or OpenAI Responses and enter the Base URL provided by the service provider.

When using a local Ollama instance, start the Ollama service and download the required model first.

2. Configure PDF Parsing

Standard text-based PDFs can be parsed locally with pdf_oxide and do not require MinerU.

For scanned PDFs or PDFs that cannot be parsed well locally, configure MinerU on the “Providers” page and then select one of the following options:

• Prefer local parsing
• Prefer MinerU
• Local parsing only
• MinerU only

If MinerU has not been configured, avoid selecting “MinerU only.”

3. Create a Translation Assistant

Open the “Assistants” page to configure:

• Assistant name and icon
• System prompt
• Custom model request parameters
• Assistant enabled status

4. Create a Translation Task

Open the “Start” page:

1. Select the source and target languages.
2. Select the translation provider, model, and assistant.
3. Select a glossary if required.
4. Configure token chunking, concurrency, retry attempts, and context mode.
5. Drag in or select a document.
6. Create the task.
7. Open the “Tasks” page to start the translation and view its progress.

Build and Verification

Frontend Type Checking and Build

pnpm build

Rust Tests

cargo test --manifest-path src-tauri/Cargo.toml

Build a Tauri Release

pnpm tauri build

The current src-tauri/tauri.conf.json contains:

{
  "bundle": {
    "active": false
  }
}

Therefore, the current configuration primarily generates a release application and does not generate installers such as MSI or NSIS packages. Release build output is located in:

src-tauri/target/release/

To publish an installer, signing, icons, installer configuration, and an update strategy must first be completed, and Tauri Bundle must be enabled.

Project Structure

InsituTranslate/
├─ public/                       Static assets and provider icons
├─ src/
│  ├─ components/
│  │  ├─ layout/                 Application shell and title bar
│  │  └─ ui/                     Shared UI components
│  ├─ features/                  Frontend modules organized by domain
│  ├─ lib/                       Shared frontend utilities
│  ├─ views/                     Application pages
│  ├─ App.tsx                    Page orchestration and global layout entry point
│  └─ main.tsx                   React entry point
├─ src-tauri/
│  ├─ capabilities/              Tauri permission configuration
│  ├─ icons/                     Desktop application icons
│  ├─ src/
│  │  ├─ document_parsing/       Document parsing and format restoration
│  │  ├─ translation/            Translation tasks and scheduling pipeline
│  │  ├─ adapters.rs             Model provider protocol adapters
│  │  ├─ commands.rs             Tauri IPC commands
│  │  ├─ db.rs                   Provider database
│  │  ├─ glossaries.rs           Glossary management
│  │  └─ settings.rs             Application settings
│  ├─ Cargo.toml
│  └─ tauri.conf.json
├─ package.json
├─ pnpm-lock.yaml
└─ vite.config.ts

Local Data

After the application starts, Tauri stores local data in the application data directory. On Windows, this is usually located at:

%APPDATA%\com.insitutranslate.desktop\

The main contents include:

providers.sqlite3
settings.sqlite3
translation-workspace/
glossary-workspace/
logs/backend.log

These files contain local runtime data and should not be committed to Git.

Deleting the application data directory will remove local provider configurations, task indexes, glossaries, and interface settings. Back up this directory before working on the database or task format.

Development Notes

• Use pnpm. Do not mix npm, Yarn, or other lockfiles into the project.
• Import animation components from motion/react. Do not install the legacy framer-motion package.
• Requests to external translation APIs must be performed by the Rust backend.
• Do not store API keys in React, TypeScript, or frontend environment variables.
• When modifying a document format parser, verify that the translated file can still be opened normally by the corresponding application.
• DOCX and XLSX write-back operations should preserve the original ZIP/XML package and modify only targeted text nodes.
• Changes to PDF, DOCX, XLSX, EPUB, and subtitle processing should include corresponding tests.
• If /0_repo_references/ exists, it may only be read as reference code. Do not modify it or add path dependencies pointing to it.

Non-Windows Platforms

The current Tauri configuration uses Windows commands:

"beforeDevCommand": "pnpm.cmd dev",
"beforeBuildCommand": "pnpm.cmd build"

As a result, macOS and Linux cannot start the project directly with the current configuration. Cross-platform support requires adjusting these commands and configuring the relevant Tauri system dependencies, permissions, window behavior, and packaging process for each platform.

The presence of mobile platform icons in the project does not mean that Android or iOS versions have been completed.

Licensing

The repository currently does not include a LICENSE file.

Until the project author explicitly adds an open-source license, do not assume that the repository permits copying, modification, redistribution, or commercial use. Obtain permission from the project author before referencing or using the code.