transpaste 0.1.0__tar.gz

transpaste-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: transpaste
+Version: 0.1.0
+Summary: A local LLM-based clipboard translator
+Author-email: CodeOfMe <wedonotuse@outlook.com>
+License: GPL-3.0
+Project-URL: Homepage, https://github.com/CodeOfMe/TransPaste
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: PySide6
+Requires-Dist: requests
+
+# TransPaste
+
+TransPaste is a powerful and lightweight clipboard translation tool powered by local Large Language Models (LLMs) via Ollama. Designed to seamlessly integrate into daily workflows, TransPaste automatically detects text copied to the clipboard and replaces it with a high-quality translation in the target language.
+
+## Project Background
+
+In the contemporary globalized digital environment, the necessity for rapid and accurate translation is ubiquitous. Traditional translation workflows frequently involve a tedious process of copying text, navigating to a translation website or application, pasting the text, awaiting the result, copying the translation, and finally returning to the original application to paste it. This persistent context switching disrupts focus and diminishes productivity. Furthermore, numerous online translation services necessitate transmitting sensitive data to cloud servers, precipitating significant privacy concerns for professionals handling confidential documents or personal communications.
+
+TransPaste was conceived to address these two critical issues: workflow friction and data privacy. By leveraging the capabilities of local LLMs such as `gemma3:1b` and `qwen3:0.6b` through Ollama, TransPaste ensures that data never leaves the local machine. The translation process occurs entirely on local hardware, providing assurance regarding data security. Additionally, by automating the "translate-and-replace" mechanism directly within the clipboard, TransPaste eliminates the necessity for manual context switching. Users can simply copy text in one language and immediately paste it in another, rendering cross-lingual communication as natural as native typing. This project represents a progression towards more integrated, private, and efficient AI-assisted productivity tools.
+
+## Application Scenarios
+
+TransPaste is versatile and applicable in numerous scenarios characterized by language barriers.
+
+1.  **Cross-Border E-Commerce & Customer Support**: Support agents frequently need to communicate with customers in multiple languages. TransPaste facilitates the copying of a customer's query for instant comprehension, or the drafting of a response in a native language followed by the pasting of a translated version directly into the chat window, significantly accelerating response times.
+2.  **Software Development**: Developers often encounter documentation, error messages, or code comments in languages not fluently spoken. With TransPaste, error logs in languages such as Japanese or Chinese can be copied and the English explanation pasted into notes or search engines, streamlining the debugging process. It also assists in variable naming by translating concepts into English identifiers.
+3.  **Academic Research & Reading**: Researchers reviewing international papers can copy paragraphs of foreign text and paste the translation into summary notes. This fluid workflow encourages deeper engagement with international sources without the distraction of constant tab-switching.
+4.  **Language Learning**: Language learners can utilize TransPaste to verify understanding. By copying a written sentence and pasting it back, the AI translation can be observed, or conversely, a foreign sentence can be copied to obtain an instant translation, reinforcing vocabulary and grammar knowledge in real-time.
+
+## Compatible Hardware
+
+Since TransPaste relies on local LLM inference provided by Ollama, hardware requirements are primarily dictated by the chosen model.
+
+*   **Processor (CPU)**: A modern multi-core processor (Intel Core i5/i7/i9 or AMD Ryzen 5/7/9) is recommended. While Ollama can operate on CPU only, performance scales significantly with superior CPU clock speeds and core counts, particularly for quantized models.
+*   **Graphics Card (GPU)**: For the optimal experience, a dedicated NVIDIA GPU with CUDA support is highly recommended. A GPU with at least 4GB of VRAM can comfortably execute smaller models like `gemma3:1b` or `qwen3:0.6b`. For larger models (7B parameter and above), 8GB to 16GB of VRAM is advisable to ensure near-instantaneous translations.
+*   **Memory (RAM)**: System memory is crucial, especially if running models on the CPU or if the model size exceeds the GPU's VRAM. A minimum of 8GB RAM is required for basic operation with small models. 16GB or 32GB is recommended for smoother multitasking, ensuring that the translation process does not impede other active applications.
+*   **Storage**: An SSD (Solid State Drive) is strongly recommended over an HDD. Loading models into memory necessitates rapid read speeds. Sufficient disk space is required to store the models themselves; small models may occupy 1-2GB, while larger, higher-quality models can consume 5GB to 20GB or more.
+
+## Operating System
+
+TransPaste is constructed using Python and the PySide6 framework (Qt for Python), rendering it inherently cross-platform.
+
+*   **Windows**: The application is fully tested and optimized for Windows 10 and Windows 11. It integrates seamlessly with the Windows system tray and clipboard subsystem. The provided screenshots and instructions are based on the Windows environment, ensuring a native aesthetic and experience.
+*   **Linux**: Linux users (specifically Ubuntu 24.04) can also operate TransPaste. The application forces the use of the XCB plugin to ensure compatibility with clipboard operations, even on Wayland-based systems (via XWayland).
+    *   **Requirements**: Ensure `libxcb` and related libraries are installed. On Ubuntu:
+        ```bash
+        sudo apt install libxcb-cursor0 libxcb-xinerama0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-shape0 libxcb-sync1 libxcb-xfixes0 libxcb-xkb1 libxkbcommon-x11-0
+        ```
+    *   This ensures the PySide6 application can launch and interact with the system tray and clipboard correctly.
+
+## Dependencies
+
+To execute TransPaste successfully, several software components and Python libraries must be installed and configured on the system.
+
+1.  **Python 3.10+**: The core application is written in Python. A relatively recent version of Python is required. Python 3.10 or newer is recommended to ensure compatibility with the latest type hinting features and library optimizations.
+2.  **Ollama**: This serves as the backend engine powering the translations. Ollama must be downloaded and installed from [ollama.com](https://ollama.com). Ollama acts as a local server hosting the LLMs and exposing an API to which TransPaste connects. At least one model (e.g., `ollama pull gemma3:1b`) must be pulled for the application to function.
+3.  **PySide6**: This library provides the graphical user interface (GUI) bindings for the Qt framework. It allows TransPaste to create the system tray icon, menus, and efficiently handle system-level clipboard events. It is a robust and mature framework for desktop application development.
+4.  **Requests**: A simple yet powerful HTTP library for Python. TransPaste utilizes `requests` to communicate with the local Ollama API server, handling the transmission of prompts and the reception of generated translations.
+5.  **Regex (re)**: A built-in Python module utilized for post-processing text to ensure clean output by stripping unnecessary quotes or conversational filler from the LLM's response.
+
+## Installation Process
+
+Follow these steps to set up TransPaste on a local machine.
+
+1.  **Install Ollama**:
+    *   Visit [ollama.com](https://ollama.com) and download the installer for the operating system.
+    *   Run the installer and adhere to the on-screen instructions.
+    *   Open a terminal or command prompt and execute `ollama run gemma3:1b` (or `qwen3:0.6b`) to download and verify the model is functioning. Maintain the Ollama service running in the background.
+
+2.  **Clone the Repository**:
+    *   Open a terminal.
+    *   Navigate to the desired directory for the project.
+    *   Execute: `git clone https://github.com/CodeOfMe/TransPaste.git`
+    *   Enter the directory: `cd TransPaste`
+
+3.  **Set Up Python Environment**:
+    *   (Optional but recommended) Create a virtual environment: `python -m venv venv`
+    *   Activate the virtual environment:
+        *   Windows: `venv\Scripts\activate`
+        *   Linux: `source venv/bin/activate`
+
+4.  **Install Dependencies**:
+    *   Since TransPaste is a Python package, installation is simple via pip:
+        ```bash
+        pip install .
+        ```
+    *   Or, if installing from PyPI (once published):
+        ```bash
+        pip install transpaste
+        ```
+
+5.  **Run the Application**:
+    *   Execute the command: `transpaste`
+    *   A clipboard icon should appear in the system tray, indicating that TransPaste is active.
+    *   Command line options are also available:
+        ```bash
+        transpaste --model qwen3:0.6b --target French
+        ```
+
+## Running Screenshots
+
+Below are screenshots demonstrating the usage and configuration of TransPaste.
+
+### 1. Enable/Disable Toggle
+This feature provides a quick way to pause translation without exiting the application. When disabled, the clipboard contents remain untouched, allowing for standard copy-paste operations.
+
+![Enable/Disable Toggle](images/2-启用开关.png)
+
+### 2. Source Language Selection
+Right-click the system tray icon to access the menu. Under "Source Language," the language of the text being copied can be selected. "Auto Detect" is recommended for general use, allowing the model to infer the source language automatically.
+
+![Source Language Selection](images/0-原始语言选择.png)
+
+### 3. Target Language Selection
+This menu permits the definition of the target language for translation. By default, it is set to English, but switching to Chinese, Japanese, French, and many others is easily accomplished depending on immediate requirements.
+
+![Target Language Selection](images/1-目标语言选择.png)
+
+### 4. Model Selection
+TransPaste allows the selection of the local LLM to be utilized for translation. This menu dynamically populates based on the models available in Ollama. Switching between models like `gemma3:1b` or `qwen3:0.6b` can be performed instantly.
+
+![Model Selection](images/3-模型选择.png)
+
+## Authorization Agreement
+
+TransPaste is free and open-source software licensed under the **GNU General Public License v3.0 (GPLv3)**.
+
+This software is provided with the freedom to use, study, share, and modify. Redistribution and modification are permitted under the terms of the GPLv3, ensuring the software remains free and open for the community.

transpaste-0.1.0/README.md

@@ -0,0 +1,118 @@
+# TransPaste
+
+TransPaste is a powerful and lightweight clipboard translation tool powered by local Large Language Models (LLMs) via Ollama. Designed to seamlessly integrate into daily workflows, TransPaste automatically detects text copied to the clipboard and replaces it with a high-quality translation in the target language.
+
+## Project Background
+
+In the contemporary globalized digital environment, the necessity for rapid and accurate translation is ubiquitous. Traditional translation workflows frequently involve a tedious process of copying text, navigating to a translation website or application, pasting the text, awaiting the result, copying the translation, and finally returning to the original application to paste it. This persistent context switching disrupts focus and diminishes productivity. Furthermore, numerous online translation services necessitate transmitting sensitive data to cloud servers, precipitating significant privacy concerns for professionals handling confidential documents or personal communications.
+
+TransPaste was conceived to address these two critical issues: workflow friction and data privacy. By leveraging the capabilities of local LLMs such as `gemma3:1b` and `qwen3:0.6b` through Ollama, TransPaste ensures that data never leaves the local machine. The translation process occurs entirely on local hardware, providing assurance regarding data security. Additionally, by automating the "translate-and-replace" mechanism directly within the clipboard, TransPaste eliminates the necessity for manual context switching. Users can simply copy text in one language and immediately paste it in another, rendering cross-lingual communication as natural as native typing. This project represents a progression towards more integrated, private, and efficient AI-assisted productivity tools.
+
+## Application Scenarios
+
+TransPaste is versatile and applicable in numerous scenarios characterized by language barriers.
+
+1.  **Cross-Border E-Commerce & Customer Support**: Support agents frequently need to communicate with customers in multiple languages. TransPaste facilitates the copying of a customer's query for instant comprehension, or the drafting of a response in a native language followed by the pasting of a translated version directly into the chat window, significantly accelerating response times.
+2.  **Software Development**: Developers often encounter documentation, error messages, or code comments in languages not fluently spoken. With TransPaste, error logs in languages such as Japanese or Chinese can be copied and the English explanation pasted into notes or search engines, streamlining the debugging process. It also assists in variable naming by translating concepts into English identifiers.
+3.  **Academic Research & Reading**: Researchers reviewing international papers can copy paragraphs of foreign text and paste the translation into summary notes. This fluid workflow encourages deeper engagement with international sources without the distraction of constant tab-switching.
+4.  **Language Learning**: Language learners can utilize TransPaste to verify understanding. By copying a written sentence and pasting it back, the AI translation can be observed, or conversely, a foreign sentence can be copied to obtain an instant translation, reinforcing vocabulary and grammar knowledge in real-time.
+
+## Compatible Hardware
+
+Since TransPaste relies on local LLM inference provided by Ollama, hardware requirements are primarily dictated by the chosen model.
+
+*   **Processor (CPU)**: A modern multi-core processor (Intel Core i5/i7/i9 or AMD Ryzen 5/7/9) is recommended. While Ollama can operate on CPU only, performance scales significantly with superior CPU clock speeds and core counts, particularly for quantized models.
+*   **Graphics Card (GPU)**: For the optimal experience, a dedicated NVIDIA GPU with CUDA support is highly recommended. A GPU with at least 4GB of VRAM can comfortably execute smaller models like `gemma3:1b` or `qwen3:0.6b`. For larger models (7B parameter and above), 8GB to 16GB of VRAM is advisable to ensure near-instantaneous translations.
+*   **Memory (RAM)**: System memory is crucial, especially if running models on the CPU or if the model size exceeds the GPU's VRAM. A minimum of 8GB RAM is required for basic operation with small models. 16GB or 32GB is recommended for smoother multitasking, ensuring that the translation process does not impede other active applications.
+*   **Storage**: An SSD (Solid State Drive) is strongly recommended over an HDD. Loading models into memory necessitates rapid read speeds. Sufficient disk space is required to store the models themselves; small models may occupy 1-2GB, while larger, higher-quality models can consume 5GB to 20GB or more.
+
+## Operating System
+
+TransPaste is constructed using Python and the PySide6 framework (Qt for Python), rendering it inherently cross-platform.
+
+*   **Windows**: The application is fully tested and optimized for Windows 10 and Windows 11. It integrates seamlessly with the Windows system tray and clipboard subsystem. The provided screenshots and instructions are based on the Windows environment, ensuring a native aesthetic and experience.
+*   **Linux**: Linux users (specifically Ubuntu 24.04) can also operate TransPaste. The application forces the use of the XCB plugin to ensure compatibility with clipboard operations, even on Wayland-based systems (via XWayland).
+    *   **Requirements**: Ensure `libxcb` and related libraries are installed. On Ubuntu:
+        ```bash
+        sudo apt install libxcb-cursor0 libxcb-xinerama0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-shape0 libxcb-sync1 libxcb-xfixes0 libxcb-xkb1 libxkbcommon-x11-0
+        ```
+    *   This ensures the PySide6 application can launch and interact with the system tray and clipboard correctly.
+
+## Dependencies
+
+To execute TransPaste successfully, several software components and Python libraries must be installed and configured on the system.
+
+1.  **Python 3.10+**: The core application is written in Python. A relatively recent version of Python is required. Python 3.10 or newer is recommended to ensure compatibility with the latest type hinting features and library optimizations.
+2.  **Ollama**: This serves as the backend engine powering the translations. Ollama must be downloaded and installed from [ollama.com](https://ollama.com). Ollama acts as a local server hosting the LLMs and exposing an API to which TransPaste connects. At least one model (e.g., `ollama pull gemma3:1b`) must be pulled for the application to function.
+3.  **PySide6**: This library provides the graphical user interface (GUI) bindings for the Qt framework. It allows TransPaste to create the system tray icon, menus, and efficiently handle system-level clipboard events. It is a robust and mature framework for desktop application development.
+4.  **Requests**: A simple yet powerful HTTP library for Python. TransPaste utilizes `requests` to communicate with the local Ollama API server, handling the transmission of prompts and the reception of generated translations.
+5.  **Regex (re)**: A built-in Python module utilized for post-processing text to ensure clean output by stripping unnecessary quotes or conversational filler from the LLM's response.
+
+## Installation Process
+
+Follow these steps to set up TransPaste on a local machine.
+
+1.  **Install Ollama**:
+    *   Visit [ollama.com](https://ollama.com) and download the installer for the operating system.
+    *   Run the installer and adhere to the on-screen instructions.
+    *   Open a terminal or command prompt and execute `ollama run gemma3:1b` (or `qwen3:0.6b`) to download and verify the model is functioning. Maintain the Ollama service running in the background.
+
+2.  **Clone the Repository**:
+    *   Open a terminal.
+    *   Navigate to the desired directory for the project.
+    *   Execute: `git clone https://github.com/CodeOfMe/TransPaste.git`
+    *   Enter the directory: `cd TransPaste`
+
+3.  **Set Up Python Environment**:
+    *   (Optional but recommended) Create a virtual environment: `python -m venv venv`
+    *   Activate the virtual environment:
+        *   Windows: `venv\Scripts\activate`
+        *   Linux: `source venv/bin/activate`
+
+4.  **Install Dependencies**:
+    *   Since TransPaste is a Python package, installation is simple via pip:
+        ```bash
+        pip install .
+        ```
+    *   Or, if installing from PyPI (once published):
+        ```bash
+        pip install transpaste
+        ```
+
+5.  **Run the Application**:
+    *   Execute the command: `transpaste`
+    *   A clipboard icon should appear in the system tray, indicating that TransPaste is active.
+    *   Command line options are also available:
+        ```bash
+        transpaste --model qwen3:0.6b --target French
+        ```
+
+## Running Screenshots
+
+Below are screenshots demonstrating the usage and configuration of TransPaste.
+
+### 1. Enable/Disable Toggle
+This feature provides a quick way to pause translation without exiting the application. When disabled, the clipboard contents remain untouched, allowing for standard copy-paste operations.
+
+![Enable/Disable Toggle](images/2-启用开关.png)
+
+### 2. Source Language Selection
+Right-click the system tray icon to access the menu. Under "Source Language," the language of the text being copied can be selected. "Auto Detect" is recommended for general use, allowing the model to infer the source language automatically.
+
+![Source Language Selection](images/0-原始语言选择.png)
+
+### 3. Target Language Selection
+This menu permits the definition of the target language for translation. By default, it is set to English, but switching to Chinese, Japanese, French, and many others is easily accomplished depending on immediate requirements.
+
+![Target Language Selection](images/1-目标语言选择.png)
+
+### 4. Model Selection
+TransPaste allows the selection of the local LLM to be utilized for translation. This menu dynamically populates based on the models available in Ollama. Switching between models like `gemma3:1b` or `qwen3:0.6b` can be performed instantly.
+
+![Model Selection](images/3-模型选择.png)
+
+## Authorization Agreement
+
+TransPaste is free and open-source software licensed under the **GNU General Public License v3.0 (GPLv3)**.
+
+This software is provided with the freedom to use, study, share, and modify. Redistribution and modification are permitted under the terms of the GPLv3, ensuring the software remains free and open for the community.

transpaste-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "transpaste"
+version = "0.1.0"
+description = "A local LLM-based clipboard translator"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "GPL-3.0"}
+authors = [
+  {name = "CodeOfMe", email = "wedonotuse@outlook.com"}
+]
+dependencies = [
+  "PySide6",
+  "requests",
+]
+
+[project.scripts]
+transpaste = "transpaste.main:main"
+
+[project.urls]
+"Homepage" = "https://github.com/CodeOfMe/TransPaste"

transpaste-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

transpaste-0.1.0/src/transpaste/__init__.py

@@ -0,0 +1,5 @@
+from .main import main
+
+__version__ = "0.1.0"
+
+__all__ = ["main"]

transpaste-0.1.0/src/transpaste/main.py

@@ -0,0 +1,371 @@
+import sys
+import time
+import requests
+import json
+import re
+import os
+import argparse
+from PySide6.QtWidgets import QApplication, QSystemTrayIcon, QMenu, QMessageBox
+from PySide6.QtGui import QIcon, QClipboard, QAction
+from PySide6.QtCore import QObject, QThread, Signal, Slot, QTimer
+
+# -----------------------------------------------------------------------------
+# Configuration
+# -----------------------------------------------------------------------------
+OLLAMA_API_URL = "http://localhost:11434/api/generate"
+OLLAMA_TAGS_URL = "http://localhost:11434/api/tags"
+DEFAULT_MODEL = "gemma3:1b"
+TIMEOUT_SECONDS = 120
+
+# Force XCB on Linux to ensure clipboard access (XWayland compatibility)
+if sys.platform.startswith("linux"):
+    os.environ["QT_QPA_PLATFORM"] = "xcb"
+
+# A subset of common languages for the menu.
+LANGUAGE_MAP = {
+    "Auto Detect": "auto",
+    "English": "en",
+    "Chinese (Simplified)": "zh-Hans",
+    "Chinese (Traditional)": "zh-Hant",
+    "Japanese": "ja",
+    "Korean": "ko",
+    "French": "fr",
+    "German": "de",
+    "Spanish": "es",
+    "Russian": "ru",
+    "Italian": "it",
+    "Portuguese": "pt",
+}
+
+PROMPT_TEMPLATE = """You are a professional {SOURCE_LANG} ({SOURCE_CODE}) to {TARGET_LANG} ({TARGET_CODE}) translator. Your goal is to accurately convey the meaning and nuances of the original {SOURCE_LANG} text while adhering to {TARGET_LANG} grammar, vocabulary, and cultural sensitivities.
+Produce only the {TARGET_LANG} translation, without any additional explanations, notes, or commentary. Do not repeat the original text. Do not say "Here is the translation".
+
+Please translate the following {SOURCE_LANG} text into {TARGET_LANG}:
+
+
+{TEXT}"""
+
+
+# -----------------------------------------------------------------------------
+# Worker Thread for API Calls
+# -----------------------------------------------------------------------------
+class TranslatorWorker(QThread):
+    finished = Signal(str, str)  # Emits (original_text, translated_text)
+    error = Signal(str)
+
+    def __init__(self, text, source_lang, target_lang, model):
+        super().__init__()
+        self.text = text
+        self.source_lang = source_lang
+        self.target_lang = target_lang
+        self.model = model
+
+    def run(self):
+        try:
+            # Prepare the prompt
+            source_name = self.source_lang
+            source_code = LANGUAGE_MAP.get(self.source_lang, "auto")
+            target_name = self.target_lang
+            target_code = LANGUAGE_MAP.get(self.target_lang, "en")
+
+            if source_code == "auto":
+                source_name = "Source Language"
+                source_code = "auto"
+
+            prompt = PROMPT_TEMPLATE.format(
+                SOURCE_LANG=source_name,
+                SOURCE_CODE=source_code,
+                TARGET_LANG=target_name,
+                TARGET_CODE=target_code,
+                TEXT=self.text
+            )
+
+            # Call Ollama
+            payload = {
+                "model": self.model,
+                "prompt": prompt,
+                "stream": False,
+                "options": {
+                    "temperature": 0.3,
+                }
+            }
+            
+            response = requests.post(OLLAMA_API_URL, json=payload, timeout=TIMEOUT_SECONDS)
+            response.raise_for_status()
+            
+            result = response.json()
+            translated_text = result.get("response", "").strip()
+            
+            # --- Post-processing ---
+            if translated_text:
+                # 1. Remove common prefixes
+                prefixes = [
+                    r"^Here is the translation.*?:",
+                    r"^Here's the translation.*?:",
+                    r"^Sure, here is the translation.*?:",
+                    r"^Translation:",
+                    r"^Translated text:",
+                ]
+                for p in prefixes:
+                    translated_text = re.sub(p, "", translated_text, flags=re.IGNORECASE | re.MULTILINE).strip()
+                
+                # 2. Smart Quote Handling
+                original_has_quotes = (
+                    (self.text.strip().startswith('"') and self.text.strip().endswith('"')) or 
+                    (self.text.strip().startswith("'") and self.text.strip().endswith("'"))
+                )
+
+                if not original_has_quotes:
+                    if translated_text.startswith('"') and translated_text.endswith('"'):
+                        translated_text = translated_text[1:-1].strip()
+                    elif translated_text.startswith("'") and translated_text.endswith("'"):
+                        translated_text = translated_text[1:-1].strip()
+
+                # 3. Remove Markdown code blocks if wrapped
+                code_block_pattern = r"^```(?:\w+)?\s*(.*?)\s*```$"
+                match = re.search(code_block_pattern, translated_text, re.DOTALL)
+                if match:
+                    translated_text = match.group(1).strip()
+
+                self.finished.emit(self.text, translated_text)
+            else:
+                self.error.emit("Empty response from Ollama")
+
+        except requests.exceptions.ReadTimeout:
+            self.error.emit(f"Timeout after {TIMEOUT_SECONDS}s. The model took too long.")
+        except Exception as e:
+            self.error.emit(str(e))
+
+
+# -----------------------------------------------------------------------------
+# Main Application Logic
+# -----------------------------------------------------------------------------
+class ClipboardTranslator(QObject):
+    def __init__(self, initial_model=DEFAULT_MODEL, initial_source="Auto Detect", initial_target="English"):
+        super().__init__()
+        self.app = QApplication.instance()
+        self.clipboard = self.app.clipboard()
+        
+        # State
+        self.is_enabled = True
+        self.current_source_lang = initial_source
+        self.current_target_lang = initial_target
+        self.current_model = initial_model
+        self.available_models = [initial_model]
+        self.last_clipboard_text = ""
+        self.ignore_next_change = False
+        self.translator_thread = None
+
+        # Fetch models
+        self.fetch_available_models()
+
+        # Setup System Tray
+        # Try to use a standard icon if theme icon fails, but theme is best for integration
+        self.tray_icon = QSystemTrayIcon(QIcon.fromTheme("edit-copy"), self.app)
+        if self.tray_icon.icon().isNull():
+             # Fallback: create a simple pixmap or use another standard icon
+             self.tray_icon.setIcon(QIcon.fromTheme("application-x-executable"))
+             
+        self.tray_icon.setToolTip(f"TransPaste (Model: {self.current_model})")
+        
+        # Setup Menu
+        self.menu = QMenu()
+        self.setup_menu()
+        self.tray_icon.setContextMenu(self.menu)
+        self.tray_icon.show()
+
+        # Connect Clipboard Signal
+        self.clipboard.dataChanged.connect(self.on_clipboard_changed)
+        
+        # Wayland Polling Fallback (1s interval)
+        if sys.platform.startswith("linux"):
+            self.poll_timer = QTimer(self)
+            self.poll_timer.timeout.connect(self.process_clipboard)
+            self.poll_timer.start(1000)
+
+        # Notification
+        self.tray_icon.showMessage(
+            "TransPaste Started", 
+            f"Model: {self.current_model}\nTarget: {self.current_target_lang}", 
+            QSystemTrayIcon.Information, 
+            3000
+        )
+
+    def setup_menu(self):
+        self.menu.clear()
+
+        # Status Action
+        status_action = QAction("Status: Enabled" if self.is_enabled else "Status: Disabled", self.menu)
+        status_action.setCheckable(True)
+        status_action.setChecked(self.is_enabled)
+        status_action.triggered.connect(self.toggle_enabled)
+        self.menu.addAction(status_action)
+        
+        self.menu.addSeparator()
+
+        # Source Language Menu
+        source_menu = self.menu.addMenu("Source Language")
+        for lang in LANGUAGE_MAP.keys():
+            action = QAction(lang, self.menu)
+            action.setCheckable(True)
+            action.setChecked(lang == self.current_source_lang)
+            action.triggered.connect(lambda checked, l=lang: self.set_source_lang(l))
+            source_menu.addAction(action)
+
+        # Target Language Menu
+        target_menu = self.menu.addMenu("Target Language")
+        for lang in LANGUAGE_MAP.keys():
+            if lang == "Auto Detect": continue 
+            action = QAction(lang, self.menu)
+            action.setCheckable(True)
+            action.setChecked(lang == self.current_target_lang)
+            action.triggered.connect(lambda checked, l=lang: self.set_target_lang(l))
+            target_menu.addAction(action)
+
+        self.menu.addSeparator()
+
+        # Model Selection Menu
+        model_menu = self.menu.addMenu("Model")
+        for model in self.available_models:
+            action = QAction(model, self.menu)
+            action.setCheckable(True)
+            action.setChecked(model == self.current_model)
+            action.triggered.connect(lambda checked, m=model: self.set_model(m))
+            model_menu.addAction(action)
+
+        # Refresh Models Action
+        refresh_action = QAction("Refresh Models", self.menu)
+        refresh_action.triggered.connect(self.refresh_models)
+        model_menu.addSeparator()
+        model_menu.addAction(refresh_action)
+
+        self.menu.addSeparator()
+        
+        # Quit Action
+        quit_action = QAction("Quit", self.menu)
+        quit_action.triggered.connect(self.app.quit)
+        self.menu.addAction(quit_action)
+
+    def toggle_enabled(self):
+        self.is_enabled = not self.is_enabled
+        self.setup_menu()
+        msg = "Translation Enabled" if self.is_enabled else "Translation Disabled"
+        self.tray_icon.showMessage("TransPaste", msg, QSystemTrayIcon.Information, 2000)
+
+    def set_source_lang(self, lang):
+        self.current_source_lang = lang
+        self.setup_menu()
+
+    def set_target_lang(self, lang):
+        self.current_target_lang = lang
+        self.setup_menu()
+
+    def set_model(self, model):
+        self.current_model = model
+        self.setup_menu()
+        self.tray_icon.setToolTip(f"TransPaste (Model: {self.current_model})")
+        print(f"Model switched to: {model}")
+
+    def fetch_available_models(self):
+        try:
+            response = requests.get(OLLAMA_TAGS_URL, timeout=2)
+            if response.status_code == 200:
+                data = response.json()
+                models = [m["name"] for m in data.get("models", [])]
+                if models:
+                    self.available_models = sorted(list(set(models)))
+                    if self.current_model not in self.available_models:
+                         # Keep current even if not in list, or fallback
+                         if DEFAULT_MODEL in self.available_models:
+                             self.available_models.append(self.current_model)
+                    self.available_models.sort()
+        except Exception as e:
+            print(f"Failed to fetch models: {e}")
+    
+    def refresh_models(self):
+        self.fetch_available_models()
+        self.setup_menu()
+        self.tray_icon.showMessage("Models Refreshed", f"Found {len(self.available_models)} models.", QSystemTrayIcon.Information, 2000)
+
+    def on_clipboard_changed(self):
+        if not self.is_enabled:
+            return
+        QTimer.singleShot(100, self.process_clipboard)
+
+    def process_clipboard(self):
+        if self.ignore_next_change:
+            self.ignore_next_change = False
+            return
+
+        text = self.clipboard.text()
+        if not text or text.strip() == "":
+            return
+
+        if text == self.last_clipboard_text:
+            return
+
+        print(f"Detected copy: {text[:20]}...")
+        
+        if self.translator_thread and self.translator_thread.isRunning():
+            try:
+                self.translator_thread.finished.disconnect(self.on_translation_finished)
+                self.translator_thread.error.disconnect(self.on_translation_error)
+                self.translator_thread.terminate()
+                self.translator_thread.wait()
+            except Exception:
+                pass
+
+        self.translator_thread = TranslatorWorker(
+            text, 
+            self.current_source_lang, 
+            self.current_target_lang, 
+            self.current_model
+        )
+        self.translator_thread.finished.connect(self.on_translation_finished)
+        self.translator_thread.error.connect(self.on_translation_error)
+        self.translator_thread.start()
+
+    def on_translation_finished(self, original_text, translated_text):
+        print(f"Translation finished: {translated_text[:20]}...")
+        
+        self.ignore_next_change = True
+        self.last_clipboard_text = translated_text
+        self.clipboard.setText(translated_text)
+        
+        self.tray_icon.showMessage(
+            "Translated", 
+            f"Result copied to clipboard.\n{translated_text[:50]}...", 
+            QSystemTrayIcon.Information, 
+            2000
+        )
+
+    def on_translation_error(self, error_msg):
+        print(f"Translation Error: {error_msg}")
+        self.tray_icon.showMessage(
+            "Translation Failed", 
+            f"Error: {error_msg}", 
+            QSystemTrayIcon.Warning, 
+            3000
+        )
+
+def main():
+    parser = argparse.ArgumentParser(description="TransPaste: Local LLM Clipboard Translator")
+    parser.add_argument("--model", type=str, default=DEFAULT_MODEL, help="Ollama model to use (default: gemma3:1b)")
+    parser.add_argument("--source", type=str, default="Auto Detect", help="Source language (default: Auto Detect)")
+    parser.add_argument("--target", type=str, default="English", help="Target language (default: English)")
+    
+    args = parser.parse_args()
+
+    app = QApplication(sys.argv)
+    app.setQuitOnLastWindowClosed(False)
+    
+    translator = ClipboardTranslator(
+        initial_model=args.model,
+        initial_source=args.source,
+        initial_target=args.target
+    )
+    
+    sys.exit(app.exec())
+
+if __name__ == "__main__":
+    main()

transpaste-0.1.0/src/transpaste.egg-info/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: transpaste
+Version: 0.1.0
+Summary: A local LLM-based clipboard translator
+Author-email: CodeOfMe <wedonotuse@outlook.com>
+License: GPL-3.0
+Project-URL: Homepage, https://github.com/CodeOfMe/TransPaste
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: PySide6
+Requires-Dist: requests
+
+# TransPaste
+
+TransPaste is a powerful and lightweight clipboard translation tool powered by local Large Language Models (LLMs) via Ollama. Designed to seamlessly integrate into daily workflows, TransPaste automatically detects text copied to the clipboard and replaces it with a high-quality translation in the target language.
+
+## Project Background
+
+In the contemporary globalized digital environment, the necessity for rapid and accurate translation is ubiquitous. Traditional translation workflows frequently involve a tedious process of copying text, navigating to a translation website or application, pasting the text, awaiting the result, copying the translation, and finally returning to the original application to paste it. This persistent context switching disrupts focus and diminishes productivity. Furthermore, numerous online translation services necessitate transmitting sensitive data to cloud servers, precipitating significant privacy concerns for professionals handling confidential documents or personal communications.
+
+TransPaste was conceived to address these two critical issues: workflow friction and data privacy. By leveraging the capabilities of local LLMs such as `gemma3:1b` and `qwen3:0.6b` through Ollama, TransPaste ensures that data never leaves the local machine. The translation process occurs entirely on local hardware, providing assurance regarding data security. Additionally, by automating the "translate-and-replace" mechanism directly within the clipboard, TransPaste eliminates the necessity for manual context switching. Users can simply copy text in one language and immediately paste it in another, rendering cross-lingual communication as natural as native typing. This project represents a progression towards more integrated, private, and efficient AI-assisted productivity tools.
+
+## Application Scenarios
+
+TransPaste is versatile and applicable in numerous scenarios characterized by language barriers.
+
+1.  **Cross-Border E-Commerce & Customer Support**: Support agents frequently need to communicate with customers in multiple languages. TransPaste facilitates the copying of a customer's query for instant comprehension, or the drafting of a response in a native language followed by the pasting of a translated version directly into the chat window, significantly accelerating response times.
+2.  **Software Development**: Developers often encounter documentation, error messages, or code comments in languages not fluently spoken. With TransPaste, error logs in languages such as Japanese or Chinese can be copied and the English explanation pasted into notes or search engines, streamlining the debugging process. It also assists in variable naming by translating concepts into English identifiers.
+3.  **Academic Research & Reading**: Researchers reviewing international papers can copy paragraphs of foreign text and paste the translation into summary notes. This fluid workflow encourages deeper engagement with international sources without the distraction of constant tab-switching.
+4.  **Language Learning**: Language learners can utilize TransPaste to verify understanding. By copying a written sentence and pasting it back, the AI translation can be observed, or conversely, a foreign sentence can be copied to obtain an instant translation, reinforcing vocabulary and grammar knowledge in real-time.
+
+## Compatible Hardware
+
+Since TransPaste relies on local LLM inference provided by Ollama, hardware requirements are primarily dictated by the chosen model.
+
+*   **Processor (CPU)**: A modern multi-core processor (Intel Core i5/i7/i9 or AMD Ryzen 5/7/9) is recommended. While Ollama can operate on CPU only, performance scales significantly with superior CPU clock speeds and core counts, particularly for quantized models.
+*   **Graphics Card (GPU)**: For the optimal experience, a dedicated NVIDIA GPU with CUDA support is highly recommended. A GPU with at least 4GB of VRAM can comfortably execute smaller models like `gemma3:1b` or `qwen3:0.6b`. For larger models (7B parameter and above), 8GB to 16GB of VRAM is advisable to ensure near-instantaneous translations.
+*   **Memory (RAM)**: System memory is crucial, especially if running models on the CPU or if the model size exceeds the GPU's VRAM. A minimum of 8GB RAM is required for basic operation with small models. 16GB or 32GB is recommended for smoother multitasking, ensuring that the translation process does not impede other active applications.
+*   **Storage**: An SSD (Solid State Drive) is strongly recommended over an HDD. Loading models into memory necessitates rapid read speeds. Sufficient disk space is required to store the models themselves; small models may occupy 1-2GB, while larger, higher-quality models can consume 5GB to 20GB or more.
+
+## Operating System
+
+TransPaste is constructed using Python and the PySide6 framework (Qt for Python), rendering it inherently cross-platform.
+
+*   **Windows**: The application is fully tested and optimized for Windows 10 and Windows 11. It integrates seamlessly with the Windows system tray and clipboard subsystem. The provided screenshots and instructions are based on the Windows environment, ensuring a native aesthetic and experience.
+*   **Linux**: Linux users (specifically Ubuntu 24.04) can also operate TransPaste. The application forces the use of the XCB plugin to ensure compatibility with clipboard operations, even on Wayland-based systems (via XWayland).
+    *   **Requirements**: Ensure `libxcb` and related libraries are installed. On Ubuntu:
+        ```bash
+        sudo apt install libxcb-cursor0 libxcb-xinerama0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 libxcb-shape0 libxcb-sync1 libxcb-xfixes0 libxcb-xkb1 libxkbcommon-x11-0
+        ```
+    *   This ensures the PySide6 application can launch and interact with the system tray and clipboard correctly.
+
+## Dependencies
+
+To execute TransPaste successfully, several software components and Python libraries must be installed and configured on the system.
+
+1.  **Python 3.10+**: The core application is written in Python. A relatively recent version of Python is required. Python 3.10 or newer is recommended to ensure compatibility with the latest type hinting features and library optimizations.
+2.  **Ollama**: This serves as the backend engine powering the translations. Ollama must be downloaded and installed from [ollama.com](https://ollama.com). Ollama acts as a local server hosting the LLMs and exposing an API to which TransPaste connects. At least one model (e.g., `ollama pull gemma3:1b`) must be pulled for the application to function.
+3.  **PySide6**: This library provides the graphical user interface (GUI) bindings for the Qt framework. It allows TransPaste to create the system tray icon, menus, and efficiently handle system-level clipboard events. It is a robust and mature framework for desktop application development.
+4.  **Requests**: A simple yet powerful HTTP library for Python. TransPaste utilizes `requests` to communicate with the local Ollama API server, handling the transmission of prompts and the reception of generated translations.
+5.  **Regex (re)**: A built-in Python module utilized for post-processing text to ensure clean output by stripping unnecessary quotes or conversational filler from the LLM's response.
+
+## Installation Process
+
+Follow these steps to set up TransPaste on a local machine.
+
+1.  **Install Ollama**:
+    *   Visit [ollama.com](https://ollama.com) and download the installer for the operating system.
+    *   Run the installer and adhere to the on-screen instructions.
+    *   Open a terminal or command prompt and execute `ollama run gemma3:1b` (or `qwen3:0.6b`) to download and verify the model is functioning. Maintain the Ollama service running in the background.
+
+2.  **Clone the Repository**:
+    *   Open a terminal.
+    *   Navigate to the desired directory for the project.
+    *   Execute: `git clone https://github.com/CodeOfMe/TransPaste.git`
+    *   Enter the directory: `cd TransPaste`
+
+3.  **Set Up Python Environment**:
+    *   (Optional but recommended) Create a virtual environment: `python -m venv venv`
+    *   Activate the virtual environment:
+        *   Windows: `venv\Scripts\activate`
+        *   Linux: `source venv/bin/activate`
+
+4.  **Install Dependencies**:
+    *   Since TransPaste is a Python package, installation is simple via pip:
+        ```bash
+        pip install .
+        ```
+    *   Or, if installing from PyPI (once published):
+        ```bash
+        pip install transpaste
+        ```
+
+5.  **Run the Application**:
+    *   Execute the command: `transpaste`
+    *   A clipboard icon should appear in the system tray, indicating that TransPaste is active.
+    *   Command line options are also available:
+        ```bash
+        transpaste --model qwen3:0.6b --target French
+        ```
+
+## Running Screenshots
+
+Below are screenshots demonstrating the usage and configuration of TransPaste.
+
+### 1. Enable/Disable Toggle
+This feature provides a quick way to pause translation without exiting the application. When disabled, the clipboard contents remain untouched, allowing for standard copy-paste operations.
+
+![Enable/Disable Toggle](images/2-启用开关.png)
+
+### 2. Source Language Selection
+Right-click the system tray icon to access the menu. Under "Source Language," the language of the text being copied can be selected. "Auto Detect" is recommended for general use, allowing the model to infer the source language automatically.
+
+![Source Language Selection](images/0-原始语言选择.png)
+
+### 3. Target Language Selection
+This menu permits the definition of the target language for translation. By default, it is set to English, but switching to Chinese, Japanese, French, and many others is easily accomplished depending on immediate requirements.
+
+![Target Language Selection](images/1-目标语言选择.png)
+
+### 4. Model Selection
+TransPaste allows the selection of the local LLM to be utilized for translation. This menu dynamically populates based on the models available in Ollama. Switching between models like `gemma3:1b` or `qwen3:0.6b` can be performed instantly.
+
+![Model Selection](images/3-模型选择.png)
+
+## Authorization Agreement
+
+TransPaste is free and open-source software licensed under the **GNU General Public License v3.0 (GPLv3)**.
+
+This software is provided with the freedom to use, study, share, and modify. Redistribution and modification are permitted under the terms of the GPLv3, ensuring the software remains free and open for the community.

transpaste-0.1.0/src/transpaste.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+src/transpaste/__init__.py
+src/transpaste/main.py
+src/transpaste.egg-info/PKG-INFO
+src/transpaste.egg-info/SOURCES.txt
+src/transpaste.egg-info/dependency_links.txt
+src/transpaste.egg-info/entry_points.txt
+src/transpaste.egg-info/requires.txt
+src/transpaste.egg-info/top_level.txt

transpaste-0.1.0/src/transpaste.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

transpaste-0.1.0/src/transpaste.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+transpaste = transpaste.main:main

transpaste-0.1.0/src/transpaste.egg-info/requires.txt

@@ -0,0 +1,2 @@
+PySide6
+requests

transpaste-0.1.0/src/transpaste.egg-info/top_level.txt

@@ -0,0 +1 @@
+transpaste