Metadata-Version: 2.4
Name: emtranslator
Version: 0.1.0
Summary: English to Monsu translator: a zero-dependency CLI tool and Python library
Author-email: RK Riad Khan <rkriad585@gmail.com>
Maintainer-email: RK Riad Khan <rkriad585@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/rkriad585
Project-URL: Repository, https://github.com/rkriad585/EMTranslator
Project-URL: Documentation, https://rkriad585.github.io/EMTranslator
Keywords: translation,monsu,language,cli
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/rkriad585/EMTranslator/refs/heads/main/logo/logo.svg" alt="English to Monsu Translator" height="150">
</p>

<h1 align="center">English to Monsu Translator</h1>

<p align="center">
  A zero-dependency Python CLI and library that translates English text into the
  fictional Monsu language using a word dictionary.
</p>

<p align="center">
  <a href="https://img.shields.io/badge/Python-3.8%2B-blue">
    <img src="https://img.shields.io/badge/Python-3.8%2B-blue" alt="Python 3.8+">
  </a>
  <a href="https://img.shields.io/badge/Version-0.1.0-blue">
    <img src="https://img.shields.io/badge/Version-0.1.0-blue" alt="Version 0.1.0">
  </a>
  <a href="https://img.shields.io/badge/License-MIT-green">
    <img src="https://img.shields.io/badge/License-MIT-green" alt="License: MIT">
  </a>
  <a href="https://img.shields.io/badge/Made%20by-rkriad585-1f78b4">
    <img src="https://img.shields.io/badge/Made%20by-rkriad585-1f78b4" alt="Made by rkriad585">
  </a>
  <!-- TODO: fill Build Status badge once a CI service (e.g. GitHub Actions) is configured -->
</p>

## Overview

`emtranslator` is a dictionary-based translator for English and the fictional
Monsu language. It ships with a 90-word built-in dictionary, a `emtrans` command
line tool, and an embeddable `Translator` Python API. The package uses only the
Python standard library, so it installs and runs anywhere Python 3.8+ is
available.

## Screenshot

<p align="center">
  <img src="https://raw.githubusercontent.com/rkriad585/EMTranslator/refs/heads/main/Screenshots/home.png" alt="home screen" width="80%">
</p>

<p align="center">
  <em>More screenshots:
    <a href="docs/screenshots.md">View all screenshots</a>
  </em>
</p>

## Table of Contents

- [Key Features](#key-features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Usage Examples](#usage-examples)
- [Documentation](#documentation)
- [Interface](#interface)
- [Architecture](#architecture)
- [Requirements](#requirements)
- [Prerequisites](#prerequisites)
- [Development](#development)
- [Contributing](#contributing)
- [Security](#security)
- [License](#license)

## Key Features

- **Word-by-word translation** using a built-in 90-word English-to-Monsu dictionary.
- **Reverse translation** (Monsu to English) via the `-r`/`--reverse` flag or the
  `Translator(reverse=True)` constructor.
- **Punctuation- and whitespace-aware**: surrounding punctuation and spacing pass
  through translation unchanged.
- **Case-insensitive lookup** with casing preserved on the translated output.
- **Unknown words are kept as-is** and reported via `missing_words()` / `--json`.
- **Extensible dictionary**: add words from the CLI (`emtrans add`) or the API
  (`add_word()`); additions persist to
  `~/.config/neostore/emtranslator/config.toml`.
- **Zero dependencies** — standard library only.

## Installation

Requires Python 3.8+.

```bash
git clone https://github.com/rkriad585/EMTranslator.git
cd EMTranslator
pip install -e .
```

This installs the `emtrans` command and the `emtranslator` package. On systems
where the Python user scripts directory is not on `PATH`, install with
`python -m pip install -e .` instead.

## Quick Start

```bash
emtrans "Hello world"
# Monsu_1 monsu_2
```

```python
from emtranslator import Translator

t = Translator()
print(t.translate("Hello world"))  # Monsu_1 monsu_2
```

## Usage Examples

Translate a sentence, preserving punctuation and unknown words:

```bash
emtrans "Hello, world! This is a test."
# Monsu_1, monsu_2! monsu_3 monsu_4 monsu_5 monsu_6.
```

Translate from Monsu back to English:

```bash
emtrans --reverse "monsu_1 monsu_2"
# hello world
```

Read from stdin:

```bash
echo "good morning" | emtrans
# monsu_13 monsu_14
```

Translate a file to another file:

```bash
emtrans translate -i input.txt -o output.txt
```

Get JSON output including words missing from the dictionary:

```bash
emtrans --json "hello zebra"
# {
#   "original": "hello zebra",
#   "translated": "monsu_1 zebra",
#   "missing": ["zebra"],
#   "reverse": false
# }
```

Add a word and list the active dictionary:

```bash
emtrans add hi monsu_91
# Added hi -> monsu_91
emtrans list
# a: monsu_5
# ...
# hi: monsu_91
```

Use the library with a custom dictionary, in reverse mode, or with word
persistence:

```python
from emtranslator import Translator

t = Translator({"hi": "salut"})
t.translate("hi there")            # salut there

rev = Translator(reverse=True)
rev.translate("monsu_1")           # hello

t2 = Translator()
t2.add_word("hola", "monsu_91")    # persisted to config.toml
t2.missing_words("hello antelope") # ['antelope']
```

## Documentation

| Document | Description |
| --- | --- |
| [Getting Started](docs/getting-started.md) | First steps: install, first translation, first word |
| [Installation](docs/installation.md) | Requirements and install instructions |
| [Usage](docs/usage.md) | CLI and library usage with examples |
| [CLI Reference](docs/cli.md) | Full `emtrans` command reference |
| [Configuration](docs/configuration.md) | User dictionary, TOML format, migration |
| [Architecture](docs/architecture.md) | Project layout and translation flow |
| [Development](docs/development.md) | Set up a dev environment and run tests |
| [Deployment](docs/deployment.md) | Packaging and running via Docker |
| [FAQ](docs/faq.md) | Frequently asked questions |
| [Troubleshooting](docs/troubleshooting.md) | Common problems and fixes |
| [Screenshots](docs/screenshots.md) | Screenshots of the project |
| [API Reference](docs/usage.md#api-reference) | `Translator` class API |

## Interface

**CLI** — `emtrans` with three subcommands: `translate` (the default), `add`, and
`list`. Run `emtrans --help` or `emtrans <subcommand> --help` for details.

**Library** — the `emtranslator` package exposes `Translator`,
`DEFAULT_DICTIONARY`, and `__version__` from the top level:

```python
from emtranslator import Translator, DEFAULT_DICTIONARY, __version__
```

## Architecture

```
EMTranslator/
├── pyproject.toml              # packaging + emtrans console script
├── src/emtranslator/
│   ├── __init__.py             # public API surface
│   ├── __main__.py             # python -m emtranslator entry point
│   ├── cli.py                  # argparse CLI (translate/add/list)
│   ├── core.py                 # Translator class + tokenizer
│   └── dictionary.py           # DEFAULT_DICTIONARY + TOML persistence
├── tests/                      # pytest suite (core + CLI)
├── tools/generate_screenshots.py  # dev tool: renders Screenshots/*.png (Pillow)
├── docs/                       # documentation
├── logo/logo.svg               # project logo
└── Screenshots/                # screenshots
```

Translation flow:

```
Input text
   -> tokenize into words / punctuation / whitespace
   -> lower-case each word and look it up
      (built-in dict + user config + optional --dictionary file)
   -> unknown words pass through unchanged
   -> re-attach punctuation and whitespace
   -> output
```

## Requirements

- Python **3.8 or newer** (declared as `requires-python = ">=3.8"`).
- No third-party runtime dependencies.

## Prerequisites

- `git` to clone the repository.
- `pip` for the package and its build backend (`setuptools>=61.0`, pulled in
  automatically by pip).

## Development

```bash
git clone https://github.com/rkriad585/EMTranslator.git
cd EMTranslator
python -m pip install -e .
python -m pytest
```

The test suite covers the `Translator` API and the CLI (via subprocess). See
[Development](docs/development.md) for details.

## Contributing

Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before
opening an issue or pull request, and note that all interactions are governed by
our [Code of Conduct](CODE_OF_CONDUCT.md).

## Security

This tool reads and writes only local files: your input text and the user
dictionary at `~/.config/neostore/emtranslator/config.toml`. It makes no network
requests. To report a security issue, see [SECURITY.md](SECURITY.md).

## License

Distributed under the MIT License. See [LICENSE](LICENSE) for details.

## Acknowledgments

- The fictional Monsu language and its vocabulary were created for this project.
- Built and maintained by [RK Riad Khan](https://github.com/rkriad585).
