Metadata-Version: 2.5
Name: mkdocs-pseudocode-i18n
Version: 0.3.2
Summary: Multilingual educational pseudocode blocks for MkDocs with automatic language detection, Pygments and MathJax
Project-URL: Homepage, https://rod2ik.gitlab.io/mkdocs-pseudocode-i18n/
Project-URL: Documentation, https://rod2ik.gitlab.io/mkdocs-pseudocode-i18n/
Project-URL: Repository, https://gitlab.com/rod2ik/mkdocs-pseudocode-i18n
Project-URL: Issues, https://gitlab.com/rod2ik/mkdocs-pseudocode-i18n/-/issues
Author: Rod2ik
License: GPL-3.0-or-later
License-File: LICENSE
Keywords: education,i18n,mathjax,mkdocs,pseudocode,pygments
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 :: Documentation
Classifier: Topic :: Education
Requires-Python: >=3.11
Requires-Dist: mkdocs<2,>=1.6
Requires-Dist: pseudocode-i18n<0.4,>=0.3.2
Requires-Dist: pygments-lexer-pseudocode-i18n<0.4,>=0.3.2
Requires-Dist: pymdown-extensions>=10.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mkdocs-material>=9.6; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.12; extra == 'dev'
Description-Content-Type: text/markdown

# mkdocs-pseudocode-i18n

| Resource | Link | Purpose |
| --- | --- | --- |
| **mkdocs-pseudocode-i18n — repository** | [gitlab.com/rod2ik/mkdocs-pseudocode-i18n](https://gitlab.com/rod2ik/mkdocs-pseudocode-i18n) | Render multilingual pseudocode directly in MkDocs pages |
| **mkdocs-pseudocode-i18n — documentation** | [rod2ik.gitlab.io/mkdocs-pseudocode-i18n](https://rod2ik.gitlab.io/mkdocs-pseudocode-i18n/) | Complete user and developer documentation |
| **pseudocode-i18n** | [gitlab.com/rod2ik/pseudocode-i18n](https://gitlab.com/rod2ik/pseudocode-i18n) | Shared grammar, language detection, formatter, Python transpiler and flowcharts |
| **pygments-lexer-pseudocode-i18n** | [gitlab.com/rod2ik/pygments-lexer-pseudocode-i18n](https://gitlab.com/rod2ik/pygments-lexer-pseudocode-i18n) | Python-like Pygments highlighting driven by the same language definitions |
| **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.2.**
**Requires:** `pseudocode-i18n >= 0.3, < 0.4` and `pygments-lexer-pseudocode-i18n >= 0.3, < 0.4`.  
**License:** GNU GPL-3.0-or-later.

`mkdocs-pseudocode-i18n` lets you put **multilingual educational pseudocode directly in MkDocs** without maintaining separate highlighters for French, Spanish, Italian, Portuguese, German and English.

Use the same generic Markdown fence everywhere:

````markdown
```pseudo
Si note >= 10 Alors:
    Afficher "Admis"
Sinon:
    Afficher "À revoir"
Fin
```
````

The plugin detects that this block is French, uses the shared Pygments lexer, preserves MathJax fragments, and keeps the original source available to the Material copy button.

## Language directives

The canonical override is:

```text
# language: fr
```

All four directive spellings are accepted:

```text
# language: fr
# language fr
# lang: fr
# lang fr
```

The same forms work with `//`. In configuration, `lang:` is also accepted as an alias for `language:`.

## Why use it?

The plugin follows the same grammar as `pseudocode-i18n`, so your documentation accepts the same classroom-friendly forms as `.pseudo` files:

- automatic language detection;
- optional language directive (`# language: fr` canonically; `language`/`lang`, optional colon);
- `Si ... Alors`, `Sinon Si`, `Sinon`, optional `FinSi` and generic `Fin`;
- `Répéter N fois` and `Répéter ... Jusqu'à`;
- `Afficher` / `Écrire`, `Saisir` / `Lire`, `Mostrar` / `Escribir`, and localized equivalents;
- optional typed declarations with integer, float/real, string, boolean, array/list, dictionary, set and tuple;
- localized null values such as `Vide`, `Vacío`, `Vuoto`, `Vazio`, `Leer` and `None`;
- `=`, `:=`, arrows and normal arithmetic/comparison operators;
- membership operators including `Dans`, localized `not in` synonyms, `∈` and `∉`;
- TeX fragments rendered through MathJax.

The language grammar is **not duplicated** in this project. It comes from `pseudocode-i18n`, and highlighting comes from `pygments-lexer-pseudocode-i18n`.

## Install

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

Enable the plugin in `mkdocs.yml`:

```yaml
plugins:
  - search
  - pseudocode
```

For Material for MkDocs, the usual highlighting extensions work well:

```yaml
markdown_extensions:
  - pymdownx.highlight
  - pymdownx.superfences
  - pymdownx.arithmatex
```

## One fence for every language

The preferred fence is simply:

````markdown
```pseudo
...
```
````

or equivalently:

````markdown
```pseudocode
...
```
````

### Français

````markdown
```pseudo
age est un entier
absent = Vide

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

### Español

````markdown
```pseudo
edad es un entero
ausente = Vacío

Si edad >= 18 Entonces:
    Escribir "Adulto"
Sino:
    Mostrar "Menor"
Fin
```
````

### Italiano

````markdown
```pseudo
eta è un intero
assente = Vuoto

Se eta >= 18 Allora:
    Mostra "Maggiorenne"
Altrimenti:
    Mostra "Minorenne"
Fine
```
````

### Português

````markdown
```pseudo
idade é um inteiro
ausente = Vazio

Se idade >= 18 Então:
    Mostrar "Adulto"
Senão:
    Mostrar "Menor"
Fim
```
````

### Deutsch

````markdown
```pseudo
alter ist eine Ganzzahl
fehlend = Leer

Wenn alter >= 18 Dann:
    Ausgeben "Volljährig"
Sonst:
    Ausgeben "Minderjährig"
Ende
```
````

### English

````markdown
```pseudo
age is an integer
missing = None

If age >= 18 Then:
    Display "Adult"
Else:
    Display "Minor"
End
```
````

The documentation deliberately presents languages in the project order **French → Spanish → Italian → Portuguese → German → English**.

## Force a language only when needed

Normally, let the plugin detect the language. If a short or ambiguous block needs help, add the universal directive inside the block:

````markdown
```pseudo
# language: es
x = 2
Mostrar x
```
````

You can also force a language with an explicit fence alias:

```text
pseudo-fr / pseudocode-fr
pseudo-es / pseudocode-es
pseudo-it / pseudocode-it
pseudo-pt / pseudocode-pt
pseudo-de / pseudocode-de
pseudo-en / pseudocode-en
```

These aliases are **explicit overrides**, not filename extensions. Pseudocode 0.3 uses one source extension, `.pseudo`, in the rest of the ecosystem.

## Shared project configuration

`mkdocs-pseudocode-i18n` uses the same `pseudocode.config.yml` as the core and lexer:

```yaml
language: auto
fallback_language: fr

mkdocs:
  inject_mathjax: true
```

Resolution for a generic `pseudo` fence is:

1. explicit fence alias (`pseudo-es`, for example);
2. language directive inside the block (`# language: xx` canonically; `language`/`lang`, optional colon);
3. configured language when it is not `auto`;
4. automatic detection from the block content;
5. `fallback_language`.

You can still force a whole MkDocs site:

```yaml
plugins:
  - pseudocode:
      language: es
```

A directive inside a generic block still has priority over that configured default, matching the core 0.3 semantics.

## Custom synonyms

Language vocabulary remains data-driven. For example:

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

Then this becomes highlightable without changing plugin code:

````markdown
```pseudo
Montrer "Bonjour"
```
````

The same override can be stored in the shared `pseudocode.config.yml` so the parser, formatter, lexer and MkDocs integration agree.

## Types, collections and null values

````markdown
```pseudo
notes est un tableau
profil est un dictionnaire
vus est un ensemble
position est un tuple
message est une chaîne
absence = Vide

Si note ∉ notes Alors:
    Afficher "Nouvelle note"
Fin
```
````

`Vide` means the same semantic null value as Python `None`. It is distinct from empty collections: `[]` is an empty list, `{}` an empty dictionary, and an empty set corresponds to `set()` / the localized set constructor supported by the core.

## Repetition

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

and:

````markdown
```pseudo
Répéter:
    n = n + 1
Jusqu'à n >= 10
Fin
```
````

are highlighted with the same structural grammar understood by the core transpiler.

## MathJax inside pseudocode

TeX fragments remain MathJax-processable:

````markdown
```pseudo
Si \Delta \geq 0 Alors:
    Afficher $x^2$
Fin
```
````

The plugin injects MathJax 3 only when requested and when a MathJax script is not already present on the page.

## Python transpilation and automatic flowcharts

Bidirectional Python transpilation lives in the semantic core. For documentation, this plugin can now turn pseudocode directly into a Mermaid flowchart fence, which lets the Mermaid support already configured in MkDocs render the diagram as SVG in the page.

Both forms are equivalent:

````markdown
```pseudo flowchart
Si x > 0 Alors:
    Afficher "positif"
Sinon:
    Afficher "négatif"
Fin
```
````

````markdown
```pseudo mermaid
Si x > 0 Alors:
    Afficher "positif"
Sinon:
    Afficher "négatif"
Fin
```
````

Explicit language fences also work, for example `pseudo-es flowchart`. The plugin emits standard Mermaid source and deliberately relies on the site's existing Mermaid renderer; it does not invoke Chromium or Mermaid CLI during a normal MkDocs build. The plugin also keeps the Mermaid container/SVG background transparent unless the site deliberately overrides it.

For example, the core can transpile:

```text
Si x ∉ valeurs Alors:
    Afficher "Absent"
Fin
```

to Python:

```python
if x not in valeurs:
    print("Absent")
```

and can export the same pseudocode as a Mermaid flowchart/algorigram. You can then embed the Mermaid output in any MkDocs setup that supports Mermaid.

## Copying source

Rendered blocks embed the original pseudocode source in a base64 data attribute. The small browser hook included by the plugin lets Material's copy action copy the **original pseudocode**, not the MathJax-modified HTML representation.

## Development

```bash
yarn setup
yarn bfc
```

`yarn setup` prefers editable sibling checkouts of:

```text
../pseudocode-i18n
../pygments-lexer-pseudocode-i18n
```

when present. This is the recommended development layout for the coordinated ecosystem.

`yarn bfc` performs version synchronization, version checks, Ruff, pytest, documentation synchronization/checking, a strict MkDocs build, and Python package build.

Documentation is part of every project change. `site/index.md` is generated from this README, and the per-language reference pages are generated from the core language YAML files.

## Versioning

`package.json` is the single source of truth for the project version. `yarn version:sync` propagates that version to `pyproject.toml`, `mkdocs_pseudocode_i18n/__init__.py` and this README.

MkDocs pages use the placeholder:

```text
__MKDOCS_PSEUDOCODE_I18N_VERSION__
```

which is replaced at documentation build time from `package.json` by the MkDocs version hook.

## Releases

A normal push updates `main` and GitLab Pages without creating a release.

A release workflow can stamp a version/tag, build the package, publish to PyPI through the configured GitLab Trusted Publishing pipeline, then create the GitLab Release.

See the full documentation for the exact project workflow.

## License

GNU GPL-3.0-or-later.

## AUTRES PROJETS de ce développeur

The Pseudocode ecosystem is designed as several small projects sharing one grammar instead of duplicating it:

- **[pseudocode-i18n](https://gitlab.com/rod2ik/pseudocode-i18n)** — parser, formatter, executor/Python transpiler, language detection and Mermaid flowcharts;
- **[pygments-lexer-pseudocode-i18n](https://gitlab.com/rod2ik/pygments-lexer-pseudocode-i18n)** — Pygments syntax highlighting using the shared multilingual definitions;
- **[vscode-pseudocode](https://gitlab.com/rod2ik/vscode-pseudocode)** — editor integration for `.pseudo` files and the Open VSX ecosystem.

See the repositories for the rest of the developer's open-source projects.
