Metadata-Version: 2.5
Name: pseudocode-i18n
Version: 0.3.0
Summary: Multilingual educational pseudocode parser, formatter, Python transpiler and flowchart exporter
Project-URL: Documentation, https://rod2ik.gitlab.io/pseudocode-i18n/
Project-URL: Repository, https://gitlab.com/rod2ik/pseudocode-i18n
Project-URL: Issues, https://gitlab.com/rod2ik/pseudocode-i18n/-/issues
Author: Rod2ik
License: GPL-3.0-or-later
License-File: LICENSE
Keywords: education,i18n,pseudocode,python,transpiler
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Education
Classifier: Topic :: Software Development :: Compilers
Requires-Python: >=3.11
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mkdocs-material>=9.6; extra == 'dev'
Requires-Dist: mkdocs<2,>=1.6; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.12; extra == 'dev'
Description-Content-Type: text/markdown

# pseudocode-i18n

| Resource | Link | Purpose |
| --- | --- | --- |
| **pseudocode-i18n — repository** | [gitlab.com/rod2ik/pseudocode-i18n](https://gitlab.com/rod2ik/pseudocode-i18n) | Multilingual parser, formatter, Python transpiler and semantic core |
| **pseudocode-i18n — documentation** | [rod2ik.gitlab.io/pseudocode-i18n](https://rod2ik.gitlab.io/pseudocode-i18n/) | Complete user and developer documentation |
| **pygments-lexer-pseudocode-i18n** | [gitlab.com/rod2ik/pygments-lexer-pseudocode-i18n](https://gitlab.com/rod2ik/pygments-lexer-pseudocode-i18n) | Pygments syntax highlighting based on the same multilingual vocabulary |
| **mkdocs-pseudocode-i18n** | [gitlab.com/rod2ik/mkdocs-pseudocode-i18n](https://gitlab.com/rod2ik/mkdocs-pseudocode-i18n) | MkDocs integration for pseudocode blocks, rendering and teaching material |
| **vscode-pseudocode** | [gitlab.com/rod2ik/vscode-pseudocode](https://gitlab.com/rod2ik/vscode-pseudocode) | VS Code / Open VSX editing experience for `.pseudo` files |

**Current version: 0.3.0.**  
**License:** GNU GPL-3.0-or-later.

`pseudocode-i18n` lets students, teachers and developers write the **same pseudocode language in several natural languages**, while keeping one common semantic model underneath.

Write a normal `.pseudo` file, in French, Spanish, Italian, Portuguese, German or English. The language can be detected automatically. The same source can then be **checked, formatted, executed, transpiled to Python, or exported as a Mermaid flowchart/algorigram**.

```text
# language: fr

age est un entier
age = 17

Si age >= 18 Alors:
    Afficher "Majeur"
Sinon:
    Afficher "Mineur"
Fin
```

Transpiles to:

```python
age: int
age = 17

if age >= 18:
    print("Majeur")
else:
    print("Mineur")
```

## Why this project?

Pseudocode used in classrooms is rarely standardized. The same ideas are written as `Afficher`, `Écrire`, `Mostrar`, `Escribir`, `Print`, `Display`, `Si ... Alors`, `If ... Then`, `FinSi`, `Fin`, or with indentation only.

`pseudocode-i18n` deliberately accepts these common teaching variants, maps them to one AST, and provides one predictable canonical formatter.

Main goals:

- one source extension for every language: **`.pseudo`**;
- automatic language detection with an explicit override when needed;
- tolerant input, but deterministic canonical formatting;
- indentation-based block semantics, like Python;
- optional `FinSi` / `FinPour` / `FinFonction`-style terminators;
- a generic optional terminator (`Fin`, `Fim`, `Fine`, `Ende`, `End`);
- localized types, constants, operators, input/output verbs and control flow;
- Python transpilation without losing useful type information;
- a shared language definition for CLI, Pygments, MkDocs and VS Code integrations.

## Install

```bash
python -m pip install pseudocode-i18n
```

On a system-managed Python installation where you deliberately use system packages:

```bash
python -m pip install --break-system-packages pseudocode-i18n
```

The package installs two equivalent commands:

```bash
pseudo
pseudocode
```

## One `.pseudo` extension, automatic language detection

Every pseudocode source file uses the same extension, regardless of language:

```text
algo.pseudo
```

In the normal case, the language is detected from the source:

```bash
pseudo algo.pseudo
```

If detection needs to be overridden, put a universal metadata directive at the beginning of the file:

```text
# language: es
```

or force it from the CLI:

```bash
pseudo --lang es algo.pseudo
```

Resolution order is:

```text
CLI/API > # language: xx > project configuration > automatic detection > fallback
```

The directive aliases `# lang: fr`, `// language: fr` and `// lang: fr` are also accepted.

## Pseudocode in several languages

The bundled languages are intentionally documented in this pedagogical order: **French, Spanish, Italian, Portuguese, German, then English**.

### Français

```text
Si note >= 10 Alors:
    Afficher "Admis"
Sinon:
    Afficher "Ajourné"
Fin
```

### Español

```text
Si nota >= 10 Entonces:
    Mostrar "Aprobado"
Sino:
    Mostrar "No aprobado"
Fin
```

### Italiano

```text
Se voto >= 10 Allora:
    Mostra "Promosso"
Altrimenti:
    Mostra "Non promosso"
Fine
```

### Português

```text
Se nota >= 10 Então:
    Mostrar "Aprovado"
Senão:
    Mostrar "Reprovado"
Fim
```

### Deutsch

```text
Wenn note >= 10 Dann:
    Ausgeben "Bestanden"
Sonst:
    Ausgeben "Nicht bestanden"
Ende
```

### English

```text
If grade >= 10 Then:
    Display "Passed"
Else:
    Display "Failed"
End
```

## Flexible conditionals, canonical formatting

French conditionals accept, among others:

```text
Si condition:
Si condition
Si condition Alors:
Si condition Alors
```

`Sinon`, `Sinon Si`, optional `Alors`, optional colons, specific terminators and generic `Fin` are also accepted.

For example, all these tolerant variants converge with `pseudo format` toward:

```text
Si condition Alors:
    Afficher "oui"
Sinon Si autre_condition Alors:
    Afficher "peut-être"
Sinon:
    Afficher "non"
Fin
```

Indentation determines the actual block structure. End markers are always optional.

## Input and output synonyms

Vocabulary is language data rather than parser code.

French examples:

```text
Afficher "Bonjour"
Écrire "Bonjour"
Ecrire "Bonjour"

Saisir n
Lire n
```

Spanish examples:

```text
Mostrar "Hola"
Escribir "Hola"

Leer n
Introducir n
```

Matching is case-insensitive, and accentless equivalents of declared accented spellings are generated automatically.

## Variables and optional types

Type declarations are **never mandatory**. You can write ordinary Python-like assignments:

```text
a = 2
a = a + 2
```

or add pedagogical type declarations:

```text
a est un entier
a, b sont des flottants
nom est une chaîne
notes est un tableau
d est un dictionnaire
vus est un ensemble
coordonnees est un tuple
```

They are preserved in Python as annotations:

```python
a: int
a: float
b: float
nom: str
notes: list
d: dict
vus: set
coordonnees: tuple
```

Bundled semantic type families:

| Semantic type | Python | French examples | English examples |
| --- | --- | --- | --- |
| integer | `int` | `entier`, `int` | `integer`, `int` |
| float | `float` | `flottant`, `réel` | `float`, `real` |
| string | `str` | `chaîne`, `str` | `string`, `str` |
| boolean | `bool` | `booléen`, `bool` | `boolean`, `bool` |
| array/list | `list` | `tableau`, `liste` | `array`, `list` |
| dictionary | `dict` | `dictionnaire`, `dict` | `dictionary`, `dict` |
| set | `set` | `ensemble`, `set` | `set` |
| tuple | `tuple` | `tuple`, `n-uplet` | `tuple` |

The same model is localized in all six bundled languages.

## `Vide` / null values are not empty collections

A localized null constant has the same semantic role as Python `None`:

```text
x = Vide
```

becomes:

```python
x = None
```

Spanish accepts `Vacío` and its automatically generated accentless form `Vacio`; the other languages provide their own localized vocabulary.

This is distinct from empty collections:

```text
[]              # empty list
{}              # empty dictionary, exactly like Python
Ensemble()      # empty set -> set()
Tuple()         # empty tuple -> tuple()
Dictionnaire()  # empty dictionary -> dict()
```

## Assignment forms

All of these are accepted as assignments:

```text
a = 2
a := 2
a <- 2
a ← 2
2 -> a
2 → a
```

The canonical formatter emits `=`.

## Membership and mathematical notation

Localized word operators and mathematical symbols are equivalent.

French examples:

```text
x Dans E
x Inclus Dans E
x ∈ E

x Pas Dans E
x Non Dans E
x Non Inclus Dans E
x ∉ E
```

They transpile to Python `in` / `not in`.

## Repeat loops

Repeat a fixed number of times:

```text
Répéter 5 fois:
    Afficher "Bonjour"
Fin
```

becomes:

```python
for _ in range(5):
    print("Bonjour")
```

Post-test repeat-until loop:

```text
n = 0
Répéter:
    n = n + 1
Jusqu'à n >= 5
```

becomes:

```python
n = 0
while True:
    n = n + 1
    if n >= 5:
        break
```

The body therefore executes at least once.

## Run, check, transpile and format

Run directly:

```bash
pseudo programme.pseudo
```

Equivalent explicit form:

```bash
pseudo run programme.pseudo
```

Check syntax:

```bash
pseudo check programme.pseudo
```

Transpile to stdout:

```bash
pseudo transpile programme.pseudo
```

Write Python output:

```bash
pseudo transpile programme.pseudo -o programme.py
```

Canonical formatting in place:

```bash
pseudo format programme.pseudo
```

Check formatting without rewriting:

```bash
pseudo format programme.pseudo --check
```

Detect/resolved language:

```bash
pseudo language programme.pseudo
```

## Flowchart / algorigram export

The same parsed AST can be exported as Mermaid flowchart source:

```bash
pseudo flowchart programme.pseudo -o programme.mmd
```

Aliases are also available:

```bash
pseudo graph programme.pseudo
pseudo algorigram programme.pseudo
pseudo algorigramme programme.pseudo
```

For:

```text
Si note >= 10 Alors:
    Afficher "Admis"
Sinon:
    Afficher "Ajourné"
Fin
```

`pseudo flowchart` generates a Mermaid `flowchart TD` graph with localized start/end and yes/no labels. `mkdocs-pseudocode-i18n` can consume this kind of output for documentation-oriented rendering.

## Python API

Automatic language resolution is the default:

```python
from pseudocode_i18n import detect_language, format_pseudocode, parse, to_mermaid, transpile

source = '''
Si x > 0 Alors:
    Afficher x
Fin
'''

detection = detect_language(source)
tree = parse(source)
python_source = transpile(source)
canonical_source = format_pseudocode(source)
mermaid = to_mermaid(source)
```

Force a language when needed:

```python
python_source = transpile(source, language="fr")
```

`detect_language()` returns the selected ISO 639-1 code together with confidence/scores through a `LanguageDetection` object.

## Project configuration and custom synonyms

Canonical project file:

```text
pseudocode.config.yml
```

Example:

```yaml
language: auto
fallback_language: fr

format:
  colons: true
  indent: 4
  end_markers: true

languages:
  fr:
    keywords:
      display:
        add:
          - Montrer
```

This makes `Montrer` an additional French display synonym **without modifying the parser**.

Bundled language data live in:

```text
pseudocode_i18n/languages/fr.yml
pseudocode_i18n/languages/es.yml
pseudocode_i18n/languages/it.yml
pseudocode_i18n/languages/pt.yml
pseudocode_i18n/languages/de.yml
pseudocode_i18n/languages/en.yml
```

They define vocabulary, patterns, end forms, type names, method/function aliases and flowchart labels. This is the preferred place for language-specific evolution.

## Add another language

Languages use ISO 639-1 two-letter codes.

For example:

```bash
yarn generate nl
```

creates the Dutch language scaffold, inserts it before English in the supported-language order, and regenerates its documentation page/navigation. Fill the translations, then run the command again to validate/regenerate.

## Development

Bootstrap:

```bash
corepack enable
yarn setup
```

Run tests:

```bash
yarn test
```

Run the documentation locally:

```bash
yarn dev
```

LAN/mobile documentation server:

```bash
yarn dev:lan
```

Full validation before committing/releasing:

```bash
yarn bfc
```

`yarn bfc` synchronizes the project version from `package.json`, validates version consistency, lints, runs tests, regenerates/checks/builds the documentation, and builds the Python package.

### Version source of truth

`package.json` is the **single source of truth** for the project version.

```bash
yarn version:sync
```

synchronizes derived Python metadata and the version displayed in this README. MkDocs narrative pages can use:

```text
__PSEUDOCODE_I18N_VERSION__
```

and `site/hooks/version.py` replaces that placeholder from `package.json` during the documentation build.

### Documentation policy

Documentation is part of every change. Grammar, CLI, configuration, formatting, transpilation, flowcharts, language data, highlighting vocabulary and development workflow changes must update their corresponding documentation in the same revision.

The MkDocs home page is generated from this README, so the repository landing page and documentation landing page cannot silently drift apart.

## License

GNU General Public License version 3 or later (**GPL-3.0-or-later**). See [`LICENSE`](https://gitlab.com/rod2ik/pseudocode-i18n/-/blob/main/LICENSE).

## AUTRES PROJETS de ce développeur

The Pseudocode ecosystem is split into small reusable projects so that each integration can share the same grammar instead of reimplementing it:

- **[pygments-lexer-pseudocode-i18n](https://gitlab.com/rod2ik/pygments-lexer-pseudocode-i18n)** — Pygments lexer using the common multilingual semantic vocabulary and Python-like token categories.
- **[mkdocs-pseudocode-i18n](https://gitlab.com/rod2ik/mkdocs-pseudocode-i18n)** — MkDocs integration for pseudocode in teaching/documentation sites.
- **[vscode-pseudocode](https://gitlab.com/rod2ik/vscode-pseudocode)** — editor integration for `.pseudo` files, formatting and language-aware authoring.

The core project is **[pseudocode-i18n](https://gitlab.com/rod2ik/pseudocode-i18n)** and its documentation is published at **[rod2ik.gitlab.io/pseudocode-i18n](https://rod2ik.gitlab.io/pseudocode-i18n/)**.
