Metadata-Version: 2.4
Name: multilingualprogramming
Version: 0.5.1
Summary: Python application for multilingual programming
Author-email: John Samuel <johnsamuelwrites@example.com>
License: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/johnsamuelwrites/multilingual
Project-URL: Documentation, https://johnsamuel.info/multilingual/
Project-URL: Repository, https://github.com/johnsamuelwrites/multilingual
Project-URL: Issues, https://github.com/johnsamuelwrites/multilingual/issues
Project-URL: Changelog, https://github.com/johnsamuelwrites/multilingual/blob/main/CHANGELOG.md
Keywords: programming-language,multilingual,compiler,transpiler,education
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Compilers
Classifier: Topic :: Software Development :: Interpreters
Classifier: Development Status :: 4 - Beta
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: roman>=3.3
Requires-Dist: python-dateutil>=2.8
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pylint; extra == "dev"
Provides-Extra: wasm
Requires-Dist: wasmtime>=1.0.0; extra == "wasm"
Provides-Extra: performance
Requires-Dist: wasmtime>=1.0.0; extra == "performance"
Requires-Dist: numpy>=1.20.0; extra == "performance"
Dynamic: license-file

# multilingual
Not yet another programming language. A multilingual one.

> **One programming model. Many human languages.**  
> Write code in your language through multilingual frontends targeting one formal core.

## Motivation

- Problem: programming is still heavily bound to English-centric syntax and keywords.
- Idea: build multiple language frontends that compile into one typed core representation.
- Today: this is a small but working prototype; you can already write and run programs in English, French, Spanish, and other supported languages.

## Project Positioning

- This is not a beginner-only teaching DSL.
- This project targets a broad Python-like subset with localized language frontends.
- Goal: language-inclusive authoring without fragmenting runtime behavior.

## Who Is This For?

`multilingual` is for teachers, language enthusiasts, programming-language hobbyists, and people exploring LLM-assisted coding workflows across multiple human languages.

## Why Multilingual

- **Language-inclusive syntax**: Use localized keywords and built-in aliases (for example, `intervalle`, `rango`, `intervallo`).
- **Single execution pipeline**: Same flow for every language: lexer -> parser -> core lowering -> semantic checks -> Python codegen -> runtime.
- **Data-driven extensibility**: Add languages by updating registries/resources, not by rewriting parser/codegen logic.
- **REPL-first experience**: Start quickly, switch languages live, inspect keywords/operators from inside REPL.

### Pipeline Illustration

![Multilingual pipeline with surface normalization](docs/assets/multilingual_pipeline_surface.svg)

## What This Is / Is Not

- `Is`: a multilingual frontend family over one formal core.
- `Is`: a research/prototyping platform for localization-aware language tooling.
- `Is`: a forward-compilation model (`surface -> core -> execution`) with no round-trip guarantee.
- `Is not`: a claim that syntax translation alone solves all onboarding barriers.
- `Is not`: full natural-language understanding.
- `Is not`: a replacement for English-heavy ecosystem docs, examples, and tooling (yet).

## Current Limitations

- Localized keywords can still feel unnatural in some languages because grammar/word order is mostly shared.
- A small declarative surface-normalization layer now supports selected alternate phrasing patterns, but coverage is still limited.
- The project supports a controlled subset (CNL-style) per language, not unconstrained natural language.
- Standard library/module APIs mostly stay canonical Python names; localization is focused on keywords and selected builtins.
- Full drop-in compatibility with arbitrary existing Python code is not claimed yet.

Details:
- Word order and naturalness: [docs/word_order_and_naturalness.md](docs/word_order_and_naturalness.md)
- Stdlib localization boundaries: [docs/stdlib_localization.md](docs/stdlib_localization.md)
- Controlled language scope: [docs/cnl_scope.md](docs/cnl_scope.md)
- Python compatibility matrix: [docs/compatibility_matrix.md](docs/compatibility_matrix.md)
- Python 3.12 compatibility roadmap: [docs/compatibility_roadmap.md](docs/compatibility_roadmap.md)

## Quick Start

Source files for this language use the `.ml` extension (for example: `hello.ml`).
Requires Python 3.12 or newer.

### Try The Playground (No Install Required)

You can try `multilingual` directly in your browser:

- Playground: https://johnsamuel.info/multilingual/playground.html

The playground lets you:

- Write code in supported human languages
- Run full execution in Pyodide
- Inspect generated Python
- Inspect generated WAT/WASM output
- Inspect generated Rust bridge code (Wasmtime workflow)

If you are evaluating the project, please test the playground with your language and open an issue with feedback:

- Issues: https://github.com/johnsamuelwrites/multilingual/issues

### 1. Install

PyPI package: https://pypi.org/project/multilingualprogramming/

Option 1 (recommended): install in a virtual environment.

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install multilingualprogramming
```

Option 2: install with `pipx` (isolated CLI install).

```bash
pipx install multilingualprogramming
```

For local development from source, use:

```bash
pip install -r requirements.txt
pip install .
```

### 2. Hello World In Multiple Languages

```text
# English
print("Hello world")

# French
afficher("Bonjour le monde")

# Spanish (another language example)
imprimir("Hola mundo")

# Japanese
表示("こんにちは世界")

```

### 3. Use the REPL (interactive mode)

Start REPL:

```bash
# 0) Direct interactive mode (like `python`)
multilingual

# 1) Explicit REPL command (same behavior as above)
multilingual repl

# 2) French mode
multilingual repl --lang fr

# Optional: show generated Python while executing
multilingual repl --show-python

# Optional: show generated WAT (WebAssembly Text) code while executing
multilingual repl --show-wat

# Optional: show generated Rust/Wasmtime bridge code while executing
multilingual repl --show-rust
```

Inside the REPL, type code and press Enter to execute.
Both `multilingual` and `multilingual repl` start the same REPL.

Default mode example (English):

```text
>>> let total = 0
>>> for i in range(4):
...     total = total + i
...
>>> print(total)
6
```

French mode example:

```text
>>> soit somme = 0
>>> pour i dans intervalle(4):
...     somme = somme + i
...
>>> afficher(somme)
6
```

French phrase aliases are also supported:

```text
si x:
    afficher("ok")
sinon si y:
    afficher("fallback")

pour chaque i dans intervalle(3):
    afficher(i)
```

REPL commands:

- `:help` show commands
- `:language <code>` switch language
- `:python` toggle generated Python display
- `:wat` toggle generated WAT (WebAssembly Text) display
- `:rust` toggle generated Rust/Wasmtime bridge code display
- `:reset` clear session state
- `:kw [XX]` show language keywords
- `:ops [XX]` show operators and symbols
- `:q` exit

Note: selected universal built-ins (for example `range`, `len`, `sum`) support localized aliases while keeping the universal names available.

### 4. Execute and inspect programs

Execution/transpilation examples and AST parsing examples are in [USAGE.md](USAGE.md).

### 5. Run A `.ml` Source File

Create a file, for example `hello.ml`:

```text
print("Hello world")
```

Run it:

```bash
multilingual hello.ml
```

Equivalent explicit form:

```bash
multilingual run hello.ml
```

Optional (force language instead of auto-detect):

```bash
multilingual hello.ml --lang fr
multilingual run hello.ml --lang fr
```

### 6. Cross-Language Module Imports

You can import `.ml` modules across languages in one program. Example:

`module_fr.ml`:

```text
soit valeur = 41
def incremente(x):
    retour x + 1
```

`main_en.ml`:

```text
import module_fr
print(module_fr.incremente(module_fr.valeur))
```

Run:

```bash
multilingual run main_en.ml --lang en
```

## Roadmap (Short)

- v0 (today): toy-but-working interpreter/transpiler, multiple languages, core constructs, REPL, and a tested end-to-end pipeline.
- next: better tooling, IDE support, more languages, stronger frontend equivalence tests, and potential LLM-assisted code translation workflows.

## What You Can Use

- Numerals across scripts: `MPNumeral`, `UnicodeNumeral`, `RomanNumeral`
- Extended numerals: `ComplexNumeral`, `FractionNumeral`, `NumeralConverter`
- Keyword model: `KeywordRegistry`, `KeywordValidator`
- Date/time: `MPDate`, `MPTime`, `MPDatetime`
- Frontend: `Lexer`, `Parser`, AST nodes, `SemanticAnalyzer`
- Runtime: `PythonCodeGenerator`, `RuntimeBuiltins`, `ProgramExecutor`, `REPL`

Additional syntax now supported:

- Type annotations (`x: int`, `def f(x: int) -> str`)
- Nested comprehension clauses (`[x for row in rows for x in row]`)
- Set literals (`{1, 2, 3}`)
- Multiple context managers (`with A() as a, B() as b`)
- Dictionary unpacking (`{**d1, **d2}`)
- Hex/oct/bin literals (`0xFF`, `0o77`, `0b101`)
- Scientific notation (`1.5e-3`)
- Async features (`async def`, `await`, `async for`, `async with`)
- Walrus operator (`:=`)

Supported pilot languages: English, French, Spanish, German, Italian, Portuguese, Polish, Dutch, Swedish, Danish, Finnish, Hindi, Arabic, Bengali, Tamil, Chinese (Simplified), Japanese.

## Run Examples

See [examples/README.md](examples/README.md) for narrative `.ml` examples
(English/French equivalents) and runnable commands.

### Japanese Surface Syntax Example

These two files compute the same result (`15`) using canonical and alternate
surface loop phrasing:

- Surface form: `examples/surface_for_ja.ml`
- Canonical form: `examples/surface_for_ja_canonical.ml`

Run:

```bash
multilingual run examples/surface_for_ja.ml --lang ja
multilingual run examples/surface_for_ja_canonical.ml --lang ja
```

### Spanish And Portuguese Surface Syntax Examples

These pairs compute the same result using canonical and iterable-first loop phrasing:

- Spanish surface: `examples/surface_for_es.ml`
- Spanish canonical: `examples/surface_for_es_canonical.ml`
- Portuguese surface: `examples/surface_for_pt.ml`
- Portuguese canonical: `examples/surface_for_pt_canonical.ml`

Run:

```bash
multilingual run examples/surface_for_es.ml --lang es
multilingual run examples/surface_for_es_canonical.ml --lang es
multilingual run examples/surface_for_pt.ml --lang pt
multilingual run examples/surface_for_pt_canonical.ml --lang pt
```

### Semantic Equivalence (English vs French)

These two snippets are semantically equivalent:

English (`examples/arithmetics_en.ml`):

```text
let a = 10
let b = 3
print("a + b =", a + b)
```

French (`examples/arithmetics_fr.ml`):

```text
soit a = 10
soit b = 3
afficher("a + b =", a + b)
```

## Documentation

Use this README for setup and workflow; use `docs/` for design rationale and policy details.

- Browser playground (interactive): https://johnsamuel.info/multilingual/playground.html
- Usage guide: [USAGE.md](USAGE.md)
- Examples guide: [examples/README.md](examples/README.md)
- Detailed reference: [docs/reference.md](docs/reference.md)
- Design overview: [docs/design.md](docs/design.md)
- Related work and differentiation: [docs/related_work.md](docs/related_work.md)
- Core formalization: [docs/core_spec.md](docs/core_spec.md)
- Frontend translation contracts: [docs/frontend_contracts.md](docs/frontend_contracts.md)
- Evaluation plan: [docs/evaluation_plan.md](docs/evaluation_plan.md)
- Word order and syntax naturalness notes: [docs/word_order_and_naturalness.md](docs/word_order_and_naturalness.md)
- Standard library localization strategy: [docs/stdlib_localization.md](docs/stdlib_localization.md)
- Controlled language scope and ambiguity policy: [docs/cnl_scope.md](docs/cnl_scope.md)
- Python compatibility matrix: [docs/compatibility_matrix.md](docs/compatibility_matrix.md)
- Python 3.12 compatibility roadmap: [docs/compatibility_roadmap.md](docs/compatibility_roadmap.md)
- Translation governance guide: [docs/translation_guidelines.md](docs/translation_guidelines.md)
- Development and debugging guide: [docs/development.md](docs/development.md)
- Guide complet en francais: [docs/fr/programmation.md](docs/fr/programmation.md)
- Language onboarding guide: [docs/language_onboarding.md](docs/language_onboarding.md)
- Contribution guide: [CONTRIBUTING.md](CONTRIBUTING.md)
- Release process: [docs/releasing.md](docs/releasing.md)
- Changelog: [CHANGELOG.md](CHANGELOG.md)

## Development

```bash
python -m pytest -q
python -m pylint $(git ls-files '*.py')
```

## License

- Code: GPLv3+
- Documentation/content: CC BY-SA 4.0
