How 9th-floor-developers/translatable-python works
What this project is (type + purpose)
This is a single-file CLI “compiler/transpiler” for a small language variant called Translatable Python (.tpy). It:
• Reads a .tpy source file and a dictionary CSV (PythonKeyword,TranslatedKeyword)
• Translates the custom keywords back into valid Python syntax
• Executes the resulting Python code (so it’s a transpile-and-run pipeline, not a standalone bytecode compiler)
The “system” is therefore best diagrammed as a language toolchain (front-end + translation + runtime execution) rather than a web service architecture.
How the file tree maps to architecture
Top-level artifacts:
• lang.py: the entire compiler/transpiler + runner (core engine and CLI entrypoint).
• template_dict.csv: a base/example dictionary template for keyword mappings.
• **examples/***: multiple sample “languages” (ru, th, kr, ar, hi, gen_alpha). Each contains:
• one *.csv dictionary file for that language
• **images/***: README screenshots (documentation-only).
What to extract from README
Key behaviors to reflect:
• Invocation: python lang.py script.tpy dict.csv
• Dictionary requirements: each Python keyword maps to a unique translated keyword; UTF-8 support
• Python version: 3.10+ preferred (for match/case support)
• Output: execution prints/side-effects like normal Python
That implies two primary external inputs (source + dictionary), a translation engine, and a Python execution runtime.
CLI Invocation Layer
• Parses args: script.tpy path, dict.csv path
File I/O Layer
• Reads .tpy source (UTF-8)
• Reads CSV dictionary (UTF-8)
Dictionary Parser / Validator
• Parses CSV rows into a mapping
• Validates constraints implied by README:
• unique mapping
• no duplicate python keywords
• (optionally) “keyword collisions” / conflicting translations
Translator / Rewriter
• Applies keyword replacements to .tpy text to produce Python source text
• (If implemented) handles tokenization/safety boundaries (e.g., avoid replacing inside strings/comments) — even if it’s naive replacement today, represent it explicitly as a stage (“Text-based replacement” vs “Token-based replacement”)
Python Code Generation Output
• “Generated Python code” as an artifact (in-memory string; optionally can be persisted for debugging)
Execution Engine
• Executes generated code (likely exec() in-process)
• Runs under Python 3 interpreter runtime
Program Output
• stdout/stderr, exceptions, exit code
Architectural patterns to call out
• Compiler pipeline pattern (input → parse/validate → transform → output)
• Transpilation (source-to-source translation: .tpy → .py)
• Interpreter embedding (generated Python executed via host Python runtime)
• Config-driven translation (CSV dictionary as configuration)
Technologies/libraries worth labeling
• Python 3.10+ runtime
• CSV dictionary (UTF-8) as configuration
Shows User, lang.py tool, and file artifacts (.tpy, dict.csv) + output.
Break lang.py into the logical components listed above (CLI, I/O, parser/validator, translator, executor).
Steps from invocation → read files → parse dict → translate → execute → output/error.
Before finalizing, open lang.py and confirm:
• Does it do pure string replace, regex, or token-based parsing?
• Does it avoid replacing inside strings/comments?
• How execution occurs:
• exec() in same process?
• compile() then exec()?
• writing a temp .py then running via subprocess?
• Error handling/reporting (line mapping from .tpy to .py?)
• “Syntax Normalizer (e.g., braces → indentation)” (if implemented)
• “Tokenizer” (if implemented)
• “Temp file writer + subprocess runner” (if that’s the execution strategy)
Don’t overthink it: decompose aggressively
• every artifact is explicit,
• and every boundary (process/filesystem/runtime) is visible.
That makes it clear what could be extended later (e.g., tokenization, better parsing, debugging outputs, multi-dict support) and matches the repo’s purpose as a lightweight transpiler tool.