Architecture

Project layout

EMTranslator/
├── pyproject.toml              # packaging, emtrans entry point, pytest config
├── README.md
├── LICENSE
├── .version                    # current version: 0.1.0
├── src/emtranslator/
│   ├── __init__.py             # exports Translator, DEFAULT_DICTIONARY, __version__
│   ├── __main__.py             # enables `python -m emtranslator`
│   ├── cli.py                  # argparse CLI: translate/add/list subcommands
│   ├── core.py                 # Translator class and tokenizer
│   └── dictionary.py           # DEFAULT_DICTIONARY, TOML persistence, migration
├── tests/
│   ├── test_core.py            # Translator API tests
│   └── test_cli.py             # CLI subprocess tests
├── docs/                       # documentation
├── logo/logo.svg               # project logo
└── Screenshots/                # screenshots

Modules

  • cli.py — builds the emtrans argparse interface, reads input (text, file, or stdin), constructs a Translator, and formats output. When the first argument is not a known subcommand, translate is assumed.
  • core.py — the Translator class. It tokenizes input with a single regular expression that captures words, punctuation, and whitespace separately, so only words are looked up. Lookup lower-cases the word; output mirrors the original casing. Unknown words are returned unchanged.
  • dictionary.py — holds the built-in 90-word DEFAULT_DICTIONARY, the config location constants, a minimal flat-table TOML reader/writer (the package has zero dependencies, so TOML support is hand-rolled), and helpers that load, save, and migrate the user dictionary.

Config location

  • User dictionary: ~/.config/neostore/emtranslator/config.toml
  • Legacy (pre-migration) location: ~/.config/emtranslator/dictionary.json

On first load of the user dictionary, migrate_user_dictionary() copies entries from the legacy JSON location to the TOML location if the new file does not exist yet.

Translation flow

Input text
   |
   v
Tokenize: (\w+) | ([^\w\s]) | (\s+)     (core.py: _TOKEN_RE)
   |
   +-- word tokens      -> lower-case -> look up in active dictionary
   |                       (built-in + user config + optional --dictionary file)
   |                       -> found:  return translation with original casing
   |                       -> missing: return the word unchanged
   +-- punctuation/space -> returned verbatim
   |
   v
Join all tokens into the translated string

The active dictionary for English-to-Monsu is the built-in dictionary updated with any constructor dictionary argument and the on-disk user dictionary. For reverse mode, the mapping is inverted with build_reverse().

Exit codes

The CLI returns 0 on success and 2 on usage errors (see CLI Reference).

See also

Back to README