Metadata-Version: 2.5
Name: pygments-lexer-pseudocode-i18n
Version: 0.8.0
Summary: Python-inspired Pygments lexer for multilingual educational pseudocode
Project-URL: Homepage, https://rod2ik.gitlab.io/pygments-lexer-pseudocode-i18n/
Project-URL: Documentation, https://rod2ik.gitlab.io/pygments-lexer-pseudocode-i18n/
Project-URL: Repository, https://gitlab.com/rod2ik/pygments-lexer-pseudocode-i18n
Project-URL: Issues, https://gitlab.com/rod2ik/pygments-lexer-pseudocode-i18n/-/issues
Author: Rod2ik
License: GPL-3.0-or-later
License-File: LICENSE
Keywords: education,i18n,lexer,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 :: Education
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: pseudocode-i18n<0.9,>=0.8.0
Requires-Dist: pygments>=2.18
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

# pygments-lexer-pseudocode-i18n

| Resource | Link | Purpose |
| --- | --- | --- |
| **pygments-lexer-pseudocode-i18n — repository** | [gitlab.com/rod2ik/pygments-lexer-pseudocode-i18n](https://gitlab.com/rod2ik/pygments-lexer-pseudocode-i18n) | Multilingual Pygments syntax highlighting for Pseudocode |
| **pygments-lexer-pseudocode-i18n — documentation** | [rod2ik.gitlab.io/pygments-lexer-pseudocode-i18n](https://rod2ik.gitlab.io/pygments-lexer-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 |
| **mkdocs-pseudocode-i18n** | [gitlab.com/rod2ik/mkdocs-pseudocode-i18n](https://gitlab.com/rod2ik/mkdocs-pseudocode-i18n) | MkDocs integration for pseudocode teaching/documentation sites |
| **vscode-pseudocode-i18n** | [gitlab.com/rod2ik/vscode-pseudocode-i18n](https://gitlab.com/rod2ik/vscode-pseudocode-i18n) | VS Code editing experience for `.pseudo` files, published on Open VSX and Visual Studio Marketplace |

**Current version: 0.8.0.**
**Requires:** `pseudocode-i18n >= 0.8.0, < 0.9`.  
**License:** GNU GPL-3.0-or-later.

`pygments-lexer-pseudocode-i18n` gives the multilingual language defined by [`pseudocode-i18n`](https://gitlab.com/rod2ik/pseudocode-i18n) **Python-like Pygments syntax highlighting** without duplicating the grammar.

Write one normal `.pseudo` file in French, Spanish, Italian, Portuguese, German, Dutch, Danish, Swedish, Norwegian, Finnish, Greek, Ukrainian, Russian or English. The generic `pseudocode` lexer detects the source language automatically, understands the same `# language: xx` override as the core (`language`/`lang`, optional colon), and maps pseudocode concepts to the same token families used by Pygments for Python.

```text
# language: fr

notes est un tableau
absent = Vide

Répéter 5 fois:
    Si note ∉ notes Alors:
        Écrire "Note inconnue"
    Sinon:
        Afficher note
    Fin
Fin
```

Types such as `entier`, `tableau`, `dictionnaire`, `ensemble` and `tuple` are highlighted like Python built-in types; `Vide` is highlighted like Python `None`; localized boolean/membership operators are highlighted like Python word operators.


All four forms below are equivalent; the first is canonical:

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

`#` is the only comment/directive marker. `//` is integer division. In `pseudocode.config.yml`, `lang:` is also accepted as an alias for `language:`.

## Why this lexer?

A pseudocode lexer becomes difficult to maintain if every editor, MkDocs plugin and highlighter carries its own handwritten list of translated keywords. This project deliberately avoids that problem.

The grammar and vocabulary come from `pseudocode-i18n`, so the lexer automatically follows the shared language definitions for:

- `Si ... Alors`, `Sinon Si`, `Sinon`, `Fin` and optional specific end markers;
- `Pour`, `Tant Que`, `Répéter N fois` and `Répéter ... Jusqu'à`;
- infinitive/imperative command synonyms such as `Afficher` / `Affiche`, `Lire` / `Lis`, `Mostrar` / `Muestra`, German `Ausgeben` / `Gib aus`, and their localized equivalents;
- optional type declarations, including arrays/lists, dictionaries, sets and tuples;
- localized `Vrai` / `Faux` / `Vide`-style constants;
- `Dans`, `Non Dans`, `Non Inclus Dans`, `∈` and `∉`;
- `=`, `:=`, arrows, arithmetic/comparison operators, strings, numbers and comments;
- localized functions and methods;
- project-specific vocabulary added through `pseudocode.config.yml`.

## Current highlighting contract

The lexer follows the 0.7 core vocabulary directly, including typed callable signatures and the localized object model. Semantic linting remains intentionally in `pseudocode-i18n`; this package is syntax highlighting only. It includes:

- `Début`/algorithm, process/subprocess and translated forms;
- localized no-fall-through switch/case (`Selon`, `Cas`, `Autrement`, ...);
- infinitive/second-person imperative aliases for action verbs, including repeat;
- no-newline output and clear-screen built-ins;
- `//`, `%`, `^`, `**`, `<>`, `!=` and localized `MOD`/logical operators;
- localized imports plus universal Python `import`, `from`, `as`;
- localized and universal Python-style built-in functions/constants such as `sqrt`, `abs`, `len`, `pow` and `pi`;
- `#` comments only.

Multi-word import aliases such as French `En tant que` are highlighted contextually on import lines, so common grammar words such as `tant` and `que` remain normal structural keywords elsewhere.

## Install

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

The core dependency is installed automatically:

```text
pseudocode-i18n >= 0.8.0, < 0.9
```

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

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

## One `.pseudo` extension

The current ecosystem uses one source extension for every language:

```text
algorithm.pseudo
```

Language-bearing filename extensions such as `.pseudo-fr`, `.pseudo-es` and `.pseudocode-fr` are not part of the file model.

For normal use, select the generic lexer:

```text
pseudocode
```

or its short alias:

```text
pseudo
```

The lexer resolves the language in the same order as the core:

```text
explicit lexer option > language directive (`language`/`lang`, optional colon) > project configuration > automatic detection > fallback
```

For example:

```text
# language: es

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

The directive is optional; normal source can simply be detected from its grammar.

## Pseudocode in several languages

Usage is generated separately for all 14 languages in the project order: **French, Spanish, Italian, Portuguese, German, Dutch, Danish, Swedish, Norwegian, Finnish, Greek, Ukrainian, Russian, then English**.

### Français

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

### Español

```text
Si nota >= 10 Entonces:
    Mostrar "Aprobado"
Sino:
    Escribir "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
```

## Python-like token categories

The visual goal is to reuse Pygments' Python token families as closely as possible, so existing Pygments themes behave naturally.

| Pseudocode role | Pygments token family | Python analogue |
| --- | --- | --- |
| structural control flow | `Keyword` | `if`, `else`, `for`, `while` |
| `Renvoyer`, etc. | `Keyword` | `return` |
| `Vrai`, `Faux`, `Vide`, etc. | `Keyword.Constant` | `True`, `False`, `None` |
| localized types | `Name.Builtin` | `int`, `list`, `dict`, `set`, `tuple` |
| `Afficher`, `Écrire`, `Saisir`, etc. | `Name.Builtin` | `print`, `input` |
| localized word operators | `Operator.Word` | `and`, `or`, `not`, `in`, `not in` |
| `∈`, `∉` | `Operator.Word` | `in`, `not in` |
| function declaration name | `Name.Function` | Python function name |
| class declaration name | `Name.Class` | Python class name |
| strings/numbers/operators | Python-like `String`, `Number.*`, `Operator` families | equivalent Python lexical role |

This is intentional: the project does not invent a separate theme model when Pygments already has mature Python-compatible styles.

## Command line with `pygmentize`

Once installed, highlight any `.pseudo` file with automatic language detection:

```bash
pygmentize -l pseudocode -f terminal256 algorithm.pseudo
```

Generate HTML:

```bash
pygmentize -l pseudocode -f html -o algorithm.html algorithm.pseudo
```

Language-specific aliases remain available as **explicit lexer choices** when an integration already knows the language:

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

They no longer imply language-specific file extensions.

## Python API

Automatic detection:

```python
from pygments import highlight
from pygments.formatters import HtmlFormatter
from pygments_lexer_pseudocode_i18n import PseudocodeLexer

source = """\
Si note >= 10 Alors:
    Afficher "Admis"
Fin
"""

html = highlight(source, PseudocodeLexer(), HtmlFormatter())
```

Force a language through the generic lexer:

```python
lexer = PseudocodeLexer(language="es")
```

Or use an explicit class:

```python
from pygments_lexer_pseudocode_i18n import PseudocodeFrenchLexer

lexer = PseudocodeFrenchLexer()
```

The explicit API choice has priority over a language directive (`# language: xx` canonically; `language`/`lang`, optional colon), just as an explicit language argument does in `pseudocode-i18n`.

## Markdown and MkDocs

After the package is installed in the environment used to build the documentation, Pygments-aware Markdown integrations can use the generic alias:

````markdown
```pseudocode
# language: fr
Si x ∈ valeurs Alors:
    Afficher x
Fin
```
````

This is the preferred fence for multilingual content because it follows the same automatic language model as `.pseudo` files.

If a site already knows the language externally, explicit aliases such as `pseudocode-fr` are still available.

## Shared project configuration

The generic lexer reads the same `pseudocode.config.yml` as `pseudocode-i18n`.

Typical configuration:

```yaml
language: auto
fallback_language: fr

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

Then this custom spelling is highlighted without modifying this lexer:

```text
Montrer "Bonjour"
```

Language-specific lexer classes keep their explicit language while still consuming that language's project overrides.

## 0.8 Unicode, 14 languages and compact TeX

The generic and explicit lexers are now generated for **14 languages**, including Greek and Cyrillic-language pseudocode. Identifiers are Unicode-aware rather than limited to Latin ranges. Language-specific lexer entry points remain generated from the core registry.

`Token.Pseudocode.Math` now recognizes the compact safe TeX subset used by the MkDocs renderer, including common symbols, `\displaystyle`, `\frac`, `\dfrac` and `\sqrt`. Renderers may opt into simple power fragments using `^` or `**`; the default standalone lexer keeps those as ordinary pseudocode operators.


## Relationship with the other Pseudocode projects

This package **highlights** pseudocode. It intentionally delegates semantics to the shared ecosystem:

```text
pseudocode-i18n
    ├── grammar / i18n / language detection
    ├── formatter
    ├── Python transpilation / execution
    ├── Mermaid flowcharts / algorigrammes
    └── highlighting vocabulary
             │
             ▼
pygments-lexer-pseudocode-i18n
             │
             ├── Pygments / HTML / terminal highlighting
             ├── MkDocs code highlighting
             └── reusable token stream for integrations
```

For example, Python transpilation and flowchart generation belong to `pseudocode-i18n`:

```bash
pseudo transpile algorithm.pseudo
pseudo flowchart algorithm.pseudo
```

This separation keeps the lexer small while guaranteeing that it follows the same language rules.

## Development

Bootstrap the project:

```bash
corepack enable
yarn setup
```

When a sibling `../pseudocode-i18n` checkout exists, `yarn setup` installs it editable first; otherwise the compatible dependency is resolved normally.

Run tests:

```bash
yarn test
```

Run documentation locally:

```bash
yarn dev
```

Expose it on the LAN:

```bash
yarn dev:lan
```

Full validation:

```bash
yarn bfc
```

`yarn bfc` synchronizes the version, checks version consistency, lints, runs the lexer regression suite, regenerates/checks/builds the documentation strictly, and builds the Python package.

### Version source of truth

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

```bash
yarn version:sync
```

synchronizes `pyproject.toml`, `pygments_lexer_pseudocode_i18n.__version__` and the version marker in this README.

Narrative/generated MkDocs pages can use:

```text
__PYGMENTS_LEXER_PSEUDOCODE_I18N_VERSION__
```

and `site/hooks/version.py` replaces it from `package.json` at build time.

### Documentation policy

Documentation is part of every change. A change to the shared grammar, supported token categories, language resolution, aliases, configuration, packaging or workflow must update the 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.

## Release workflow

A normal push updates the project and GitLab Pages without creating a release.

Before release, run:

```bash
yarn bfc
```

The tag must match the version in `package.json`; CI validates that invariant before publishing.

With the project `push` helper used by this ecosystem, a normal update remains:

```bash
push "message"
```

and a release is requested with the current `package.json` version:

```bash
push "release <version>" --release
```

## License

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

## AUTRES PROJETS de ce développeur

The Pseudocode ecosystem is intentionally split into reusable projects sharing one grammar:

- **[pseudocode-i18n](https://gitlab.com/rod2ik/pseudocode-i18n)** — multilingual parser, formatter, Python transpiler, executor, language detection and Mermaid algorigram export.
- **[mkdocs-pseudocode-i18n](https://gitlab.com/rod2ik/mkdocs-pseudocode-i18n)** — MkDocs integration for pseudocode blocks and educational documentation.
- **[vscode-pseudocode-i18n](https://gitlab.com/rod2ik/vscode-pseudocode-i18n)** — VS Code / Open VSX editing support for `.pseudo` files.

The documentation for this lexer is published at **[rod2ik.gitlab.io/pygments-lexer-pseudocode-i18n](https://rod2ik.gitlab.io/pygments-lexer-pseudocode-i18n/)**.

Compound localized type aliases are matched as complete aliases: French `n-uplet` is highlighted as a type without making `n` or `uplet` reserved identifiers; the same rule applies to multi-word aliases such as German `Reelle Zahl`.
