Metadata-Version: 2.4
Name: md2lang-oai
Version: 1.1.0
Summary: Minimal CLI to translate Markdown/text to a target locale via an OpenAI-compatible Chat Completions endpoint.
Project-URL: Repository, https://github.com/carloscasalar/md2lang-oai
License: MIT License
        
        Copyright (c) 2025
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: cli,markdown,openai,translation
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.27
Description-Content-Type: text/markdown

# md2lang-oai

Minimal CLI that translates Markdown/text into a target locale using an OpenAI-compatible **Chat Completions** HTTP endpoint.

## Quick start

Run without installing:

```bash
uvx md2lang-oai --help
```

## Usage

Translate from stdin to stdout:

```bash
echo "Hello" | uvx md2lang-oai --to es-ES
```

Translate a file:

```bash
uvx md2lang-oai --to es-ES --input README.md
```

Write to a file:

```bash
uvx md2lang-oai --to es-ES --input input.md --output output.md
```

Pipe-friendly (stdin):

```bash
cat input.md | uvx md2lang-oai --to es-ES > output.md
```

Provide custom translation instructions:

```bash
uvx md2lang-oai --to es-ES --input dnd_adventure.md --instructions-file dnd_instructions.txt
```

## Configuration

- API key is read from `OPENAI_API_KEY` by default.
- Choose a different env var name with `--api-key-env`.
- Override the endpoint with `--base-url` (must be OpenAI-compatible).
- Choose a model with `--model`.
- Adjust timeout with `--timeout` (default: 300s for slow/local models).
- Control chunking with `--max-tokens` (default: 3000 tokens per chunk).
- Provide custom translation instructions with `--instructions-file` (e.g., for domain-specific terminology).

Example:

```bash
export OPENAI_API_KEY="..."
uvx md2lang-oai --to es-ES --model gpt-4o-mini < input.md
```

### Large files and context limits

If your input exceeds the model's context window, the CLI automatically splits it into chunks by paragraph boundaries. Each chunk is translated separately and reassembled. Adjust `--max-tokens` to fit your model's limit (e.g., 3000 for small models, 8000+ for larger ones).

Example for a local Ollama model with a 4K context:

```bash
export OPENAI_API_KEY=test
uvx md2lang-oai --to es-ES --model openchat:7b --base-url http://localhost:11434/v1 --max-tokens 2000 --timeout 600 --input large-file.md --output large-file-es.md
```

### Custom translation instructions

You can provide domain-specific instructions to guide the translation process. For instance, when translating a tabletop role-playing adventure, you may want specific acronyms to be translated in a particular way:

Create a file `dnd_instructions.txt`:

```
Regarding acronyms, translate:
- STR as FUE
- DEX as DES
- CON as CON
- WIS as SAB
- CHA as CAR
```

Then use it:

```bash
uvx md2lang-oai --to es-ES --input dnd_adventure.md --instructions-file dnd_instructions.txt
```

The instructions can be plain text or Markdown and will be appended to the system prompt sent to the model.

### Markdown handling

The tool preserves Markdown structure as much as possible:

- Does **not** translate inside fenced code blocks (`...`).
- Does **not** translate inline code spans (`like this`).
- Keeps link/image syntax intact; URLs are never translated.

## Development

Install dependencies and create a virtual environment:

```bash
uv sync
```

This will create a `.venv` directory with all dependencies installed.

Run tests:

```bash
uv run pytest
```
