| Name | ltrans JSON |
| Version |
0.1.2
JSON |
| download |
| home_page | None |
| Summary | A CLI tool to translate Jupyter Notebooks (ipynb) to Markdown (md) with AI, focusing on code comment translation. |
| upload_time | 2025-08-17 11:35:47 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
llm
ai
translation
jupyter
notebook
langchain
gemini
openai
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<!-- Logo -->
<p align="center">
<h1 align="center">ltrans</h1>
<p align="center">
Jupyter Notebook AI Translator CLI
<br />
<br />
<a href="https://github.com/xyz-liu15/ltrans/issues">Report Bug</a>
·
<a href="https://github.com/xyz-liu15/ltrans/issues">Request Feature</a>
</p>
</p>
<!-- Badges -->
<p align="center">
<a href="https://pypi.org/project/ltrans/"><img src="https://img.shields.io/pypi/v/ltrans.svg" alt="PyPI Version"></a>
<a href="https://pypi.org/project/ltrans/"><img src="https://img.shields.io/pypi/pyversions/ltrans.svg" alt="Python Versions"></a>
<a href="https://github.com/xyz-liu15/ltrans/blob/main/LICENSE"><img src="https://img.shields.io/github/license/xyz-liu15/ltrans" alt="License"></a>
</p>
[Read this in Chinese (简体中文)](README.zh.md)
---
`ltrans` is a powerful command-line interface (CLI) tool designed to translate Jupyter Notebook (`.ipynb`) files from English to Chinese. It leverages advanced AI models (like Google Gemini and Qwen) to provide accurate translations while preserving the original notebook structure, code, and only translating comments within code blocks.
## ✨ Key Features
* **Intelligent Translation**: Translates Markdown cells and comments within code cells, leaving the code itself untouched.
* **AI-Powered**: Utilizes leading AI models (Google Gemini, Qwen) for high-quality, context-aware translation.
* **Efficient & Concurrent**: Processes multiple notebooks and cells concurrently for maximum speed.
* **CLI Interface**: Easy-to-use command-line tool for seamless integration into your workflow.
* **Smart Caching**: Skips already translated files. Use `--force` to re-translate.
* **Configurable**: Manage API keys and settings via a simple `config` command.
* **Connectivity Check**: Verify your API credentials and service connectivity with the `check` command.
* **Rich Output**: Beautiful and informative console output powered by `rich`.
## 🚀 Getting Started
Follow these steps to get `ltrans` up and running.
### 1. Installation
You can install `ltrans` directly from PyPI:
```bash
pip install ltrans
```
Alternatively, for development, you can install from the source:
```bash
git clone https://github.com/xyz-liu15/ltrans.git
cd ltrans
pip install -e .
```
### 2. Configuration
Before you can translate, you need to configure your AI service API keys.
**For Google Gemini:**
```bash
ltrans config --google-api-key YOUR_GOOGLE_API_KEY
```
**For Qwen (通义千问):**
```bash
ltrans config --qwen-api-key YOUR_QWEN_API_KEY --qwen-base-url YOUR_QWEN_BASE_URL
```
You can also set keys via environment variables (`GOOGLE_API_KEY`, `QWEN_API_KEY`).
### 3. Run Your First Translation
Once configured, you can start translating!
```bash
ltrans translate path/to/your/notebooks
```
The translated Markdown files will be saved in `path/to/your/notebooks-translated/`.
## 📖 Command Reference
### `translate`
The core command to perform translations.
```bash
ltrans translate SOURCE_DIR [TARGET_DIR] [OPTIONS]
```
**Arguments:**
* `SOURCE_DIR`: (Required) The directory containing your `.ipynb` files.
* `TARGET_DIR`: (Optional) The directory where translated `.md` files will be saved. Defaults to `<SOURCE_DIR>-translated`.
**Options:**
* `--provider`, `-p`: The translation service provider. `google` (default) or `qwen`.
* `--concurrency`, `-c`: Number of concurrent requests. Defaults to `5`.
* `--force`: Force re-translation of all files, even if they already exist in the target directory.
* `--gemini-model`: Specify the Gemini model to use (e.g., `gemini-1.5-pro`). Defaults to `gemini-1.5-flash`.
* `--qwen-model`: Specify the Qwen model to use. Defaults to `qwen-turbo`.
* `--google-key`: Temporarily use a specific Google API key, overriding config.
* `--qwen-key`: Temporarily use a specific Qwen API key, overriding config.
* `--qwen-url`: Temporarily use a specific Qwen Base URL, overriding config.
### `config`
Manage API credentials.
```bash
ltrans config [OPTIONS]
```
If run without options, it displays the current configuration.
**Options:**
* `--google-api-key TEXT`: Set your Google Gemini API Key.
* `--qwen-api-key TEXT`: Set your Qwen API Key.
* `--qwen-base-url TEXT`: Set your Qwen API Base URL.
### `check`
Verify connectivity to the configured AI services.
```bash
ltrans check
```
This command tests your API keys and reports whether the services are reachable.
## 🏛️ Architecture Overview
`ltrans` is built with Python using the Typer framework for its CLI. Here's a high-level overview of the translation process:
1. **File Discovery**: The tool scans the source directory for `.ipynb` files.
2. **Content Parsing**: Each notebook is read and its cells (both Markdown and code) are extracted.
3. **Task Scheduling**: Translation tasks for each cell are created and managed by an `asyncio` event loop for concurrent processing.
4. **Prompt Engineering**: Cell content is embedded in a carefully crafted prompt that instructs the AI model to translate only natural language text (prose and code comments) while preserving code and formatting.
5. **AI Translation**: The `langchain` library sends the prompts to the configured AI service (Google Gemini or Qwen). The tool includes retry logic and rate limit handling.
6. **Markdown Assembly**: The translated cell contents are assembled into a single, clean Markdown file.
7. **File Output**: The final Markdown file is saved to the target directory.
## 🤝 Contributing
Contributions are welcome! Please feel free to open an issue to report a bug or suggest a feature, or submit a pull request with your improvements.
## 📄 License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "ltrans",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "llm, ai, translation, jupyter, notebook, langchain, gemini, openai",
"author": null,
"author_email": "ShiWu <xyz.liu15@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/62/57/c0a9c837b9222d7e4ca1df499f8da2fa8b757f9e0656b9e7e4cddcf5a696/ltrans-0.1.2.tar.gz",
"platform": null,
"description": "<!-- Logo -->\r\n<p align=\"center\">\r\n <h1 align=\"center\">ltrans</h1>\r\n <p align=\"center\">\r\n Jupyter Notebook AI Translator CLI\r\n <br />\r\n <br />\r\n <a href=\"https://github.com/xyz-liu15/ltrans/issues\">Report Bug</a>\r\n \u00b7\r\n <a href=\"https://github.com/xyz-liu15/ltrans/issues\">Request Feature</a>\r\n </p>\r\n</p>\r\n\r\n<!-- Badges -->\r\n<p align=\"center\">\r\n <a href=\"https://pypi.org/project/ltrans/\"><img src=\"https://img.shields.io/pypi/v/ltrans.svg\" alt=\"PyPI Version\"></a>\r\n <a href=\"https://pypi.org/project/ltrans/\"><img src=\"https://img.shields.io/pypi/pyversions/ltrans.svg\" alt=\"Python Versions\"></a>\r\n <a href=\"https://github.com/xyz-liu15/ltrans/blob/main/LICENSE\"><img src=\"https://img.shields.io/github/license/xyz-liu15/ltrans\" alt=\"License\"></a>\r\n</p>\r\n\r\n[Read this in Chinese (\u7b80\u4f53\u4e2d\u6587)](README.zh.md)\r\n\r\n---\r\n\r\n`ltrans` is a powerful command-line interface (CLI) tool designed to translate Jupyter Notebook (`.ipynb`) files from English to Chinese. It leverages advanced AI models (like Google Gemini and Qwen) to provide accurate translations while preserving the original notebook structure, code, and only translating comments within code blocks.\r\n\r\n## \u2728 Key Features\r\n\r\n* **Intelligent Translation**: Translates Markdown cells and comments within code cells, leaving the code itself untouched.\r\n* **AI-Powered**: Utilizes leading AI models (Google Gemini, Qwen) for high-quality, context-aware translation.\r\n* **Efficient & Concurrent**: Processes multiple notebooks and cells concurrently for maximum speed.\r\n* **CLI Interface**: Easy-to-use command-line tool for seamless integration into your workflow.\r\n* **Smart Caching**: Skips already translated files. Use `--force` to re-translate.\r\n* **Configurable**: Manage API keys and settings via a simple `config` command.\r\n* **Connectivity Check**: Verify your API credentials and service connectivity with the `check` command.\r\n* **Rich Output**: Beautiful and informative console output powered by `rich`.\r\n\r\n## \ud83d\ude80 Getting Started\r\n\r\nFollow these steps to get `ltrans` up and running.\r\n\r\n### 1. Installation\r\n\r\nYou can install `ltrans` directly from PyPI:\r\n\r\n```bash\r\npip install ltrans\r\n```\r\n\r\nAlternatively, for development, you can install from the source:\r\n\r\n```bash\r\ngit clone https://github.com/xyz-liu15/ltrans.git\r\ncd ltrans\r\npip install -e .\r\n```\r\n\r\n### 2. Configuration\r\n\r\nBefore you can translate, you need to configure your AI service API keys.\r\n\r\n**For Google Gemini:**\r\n\r\n```bash\r\nltrans config --google-api-key YOUR_GOOGLE_API_KEY\r\n```\r\n\r\n**For Qwen (\u901a\u4e49\u5343\u95ee):**\r\n\r\n```bash\r\nltrans config --qwen-api-key YOUR_QWEN_API_KEY --qwen-base-url YOUR_QWEN_BASE_URL\r\n```\r\n\r\nYou can also set keys via environment variables (`GOOGLE_API_KEY`, `QWEN_API_KEY`).\r\n\r\n### 3. Run Your First Translation\r\n\r\nOnce configured, you can start translating!\r\n\r\n```bash\r\nltrans translate path/to/your/notebooks\r\n```\r\n\r\nThe translated Markdown files will be saved in `path/to/your/notebooks-translated/`.\r\n\r\n## \ud83d\udcd6 Command Reference\r\n\r\n### `translate`\r\n\r\nThe core command to perform translations.\r\n\r\n```bash\r\nltrans translate SOURCE_DIR [TARGET_DIR] [OPTIONS]\r\n```\r\n\r\n**Arguments:**\r\n\r\n* `SOURCE_DIR`: (Required) The directory containing your `.ipynb` files.\r\n* `TARGET_DIR`: (Optional) The directory where translated `.md` files will be saved. Defaults to `<SOURCE_DIR>-translated`.\r\n\r\n**Options:**\r\n\r\n* `--provider`, `-p`: The translation service provider. `google` (default) or `qwen`.\r\n* `--concurrency`, `-c`: Number of concurrent requests. Defaults to `5`.\r\n* `--force`: Force re-translation of all files, even if they already exist in the target directory.\r\n* `--gemini-model`: Specify the Gemini model to use (e.g., `gemini-1.5-pro`). Defaults to `gemini-1.5-flash`.\r\n* `--qwen-model`: Specify the Qwen model to use. Defaults to `qwen-turbo`.\r\n* `--google-key`: Temporarily use a specific Google API key, overriding config.\r\n* `--qwen-key`: Temporarily use a specific Qwen API key, overriding config.\r\n* `--qwen-url`: Temporarily use a specific Qwen Base URL, overriding config.\r\n\r\n### `config`\r\n\r\nManage API credentials.\r\n\r\n```bash\r\nltrans config [OPTIONS]\r\n```\r\n\r\nIf run without options, it displays the current configuration.\r\n\r\n**Options:**\r\n\r\n* `--google-api-key TEXT`: Set your Google Gemini API Key.\r\n* `--qwen-api-key TEXT`: Set your Qwen API Key.\r\n* `--qwen-base-url TEXT`: Set your Qwen API Base URL.\r\n\r\n### `check`\r\n\r\nVerify connectivity to the configured AI services.\r\n\r\n```bash\r\nltrans check\r\n```\r\n\r\nThis command tests your API keys and reports whether the services are reachable.\r\n\r\n## \ud83c\udfdb\ufe0f Architecture Overview\r\n\r\n`ltrans` is built with Python using the Typer framework for its CLI. Here's a high-level overview of the translation process:\r\n\r\n1. **File Discovery**: The tool scans the source directory for `.ipynb` files.\r\n2. **Content Parsing**: Each notebook is read and its cells (both Markdown and code) are extracted.\r\n3. **Task Scheduling**: Translation tasks for each cell are created and managed by an `asyncio` event loop for concurrent processing.\r\n4. **Prompt Engineering**: Cell content is embedded in a carefully crafted prompt that instructs the AI model to translate only natural language text (prose and code comments) while preserving code and formatting.\r\n5. **AI Translation**: The `langchain` library sends the prompts to the configured AI service (Google Gemini or Qwen). The tool includes retry logic and rate limit handling.\r\n6. **Markdown Assembly**: The translated cell contents are assembled into a single, clean Markdown file.\r\n7. **File Output**: The final Markdown file is saved to the target directory.\r\n\r\n## \ud83e\udd1d Contributing\r\n\r\nContributions are welcome! Please feel free to open an issue to report a bug or suggest a feature, or submit a pull request with your improvements.\r\n\r\n## \ud83d\udcc4 License\r\n\r\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A CLI tool to translate Jupyter Notebooks (ipynb) to Markdown (md) with AI, focusing on code comment translation.",
"version": "0.1.2",
"project_urls": {
"Homepage": "https://github.com/xyz-liu15/ltrans",
"Repository": "https://github.com/xyz-liu15/ltrans"
},
"split_keywords": [
"llm",
" ai",
" translation",
" jupyter",
" notebook",
" langchain",
" gemini",
" openai"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ce85cf4f49c096992c348b3954e800914d610919d2f8090fb5d826455417f63a",
"md5": "2aca56a0b97e72e0f7a68a7270a50f8d",
"sha256": "7647124afdea03d9afd748f9cc6265eb6bb5802e5f4b95ef974d9a7d5e40720a"
},
"downloads": -1,
"filename": "ltrans-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2aca56a0b97e72e0f7a68a7270a50f8d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 9914,
"upload_time": "2025-08-17T11:35:46",
"upload_time_iso_8601": "2025-08-17T11:35:46.608768Z",
"url": "https://files.pythonhosted.org/packages/ce/85/cf4f49c096992c348b3954e800914d610919d2f8090fb5d826455417f63a/ltrans-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6257c0a9c837b9222d7e4ca1df499f8da2fa8b757f9e0656b9e7e4cddcf5a696",
"md5": "41bfe9cf0972f9132dbc556db2b32eaa",
"sha256": "4baa634170e5d96eb913814a9093ac2652ebba170e48ea7d6a1c7f852d5ad3be"
},
"downloads": -1,
"filename": "ltrans-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "41bfe9cf0972f9132dbc556db2b32eaa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 13060,
"upload_time": "2025-08-17T11:35:47",
"upload_time_iso_8601": "2025-08-17T11:35:47.625398Z",
"url": "https://files.pythonhosted.org/packages/62/57/c0a9c837b9222d7e4ca1df499f8da2fa8b757f9e0656b9e7e4cddcf5a696/ltrans-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-17 11:35:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "xyz-liu15",
"github_project": "ltrans",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "ltrans"
}
