Skip to content

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

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 - Stdlib localization boundaries: docs/stdlib_localization.md - Controlled language scope: docs/cnl_scope.md - Python compatibility matrix: docs/compatibility_matrix.md - Python 3.12 compatibility roadmap: 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.

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).

pipx install multilingualprogramming

For local development from source, use:

pip install -r requirements.txt
pip install .

2. Hello World In Multiple Languages

# 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:

# 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):

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

French mode example:

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

French phrase aliases are also supported:

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.

5. Run A .ml Source File

Create a file, for example hello.ml:

print("Hello world")

Run it:

multilingual hello.ml

Equivalent explicit form:

multilingual run hello.ml

Optional (force language instead of auto-detect):

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:

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

main_en.ml:

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

Run:

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
  • WAT/WASM backend: WATCodeGenerator — compiles multilingual AST to executable WebAssembly (core language + OOP with stateful class instances)

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 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:

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:

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):

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

French (examples/arithmetics_fr.ml):

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.

Development

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

License

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