Pseudocode-i18n for Thonny

Use multilingual .pseudo and .algo files in Thonny 5 with the same parser, diagnostics, completions, i18n snippets and navigation as the rest of the pseudocode-i18n ecosystem.

Current version: 0.9.12. Release history: thonny-pseudocode-i18n changelog.

Current Thonny experience

The plugin behaves like a native pedagogical Thonny frontend while keeping language intelligence and execution semantics shared:

• syntax coloring uses Thonny's native Python semantic tags. No Pseudocode Light/Dark palette is imposed: Default Light, Default Dark, Zenburn and other themes decide colors from Python-equivalent roles;
• function/class declarations receive definition + function_definition / definition + class_definition; localized constructors are function definitions; self / this remain visually ordinary like Python self;
• live diagnostics use a 300 ms debounce and underline error/warning/information ranges with red/orange/blue severity accents adapted to light/dark backgrounds; the Diagnostics tab uses the same red/orange/blue severity colours, renders the localized all-clear message in theme-aware green, refreshes without stealing focus, and exposes each Lxx marker as a link back to the exact editor line/column;
• the docked view is visible by default and ordered Diagnostics → Exécution pas à pas → Documentation → Algorigramme → Informations (localized from the IDE UI language); when a .pseudo / .algo file becomes active, Diagnostics is selected automatically once for that editor activation, while later refreshes do not steal a deliberately selected tab; all five tabs are disabled whenever the active editor is not a .pseudo / .algo document, and are re-enabled immediately when a Pseudocode tab becomes active;
• the Documentation tab reads the shared human-editable catalogue from pseudocode-i18n/pseudocode_i18n/documentation/<code>.yml: one YAML file per language with direct title, description and examples fields, while syntax/aliases remain generated from the grammar. Thonny therefore does not maintain a second drifting copy of the pedagogical content;
• Exécution pas à pas consumes the shared pseudocode-tutor/v2 model from the LSP/core in a three-column Source | État | Algorigramme layout. État keeps Variables, Pile d’appels and Sortie as separate zones; one-step advance and automatic Play are separate controls, with Pause and adjustable speed; no execution engine is duplicated in the plugin. Error-level Diagnostics block Tutor execution: Source and Tutor Algorigramme both show the same complete clickable diagnostic set, while source code, execution/export controls and runtime state disappear. With only warnings/information, the same diagnostics stay visible above the controls/source and above the Algorigramme while execution remains enabled. The executable source is explicitly read-only (🔒), syntax-colored with Thonny's active theme and separated into per-line bands. Tutor variable values render source-language boolean/null literals and scope/event labels come from the localized core display fields while machine values/identifiers remain untouched;
• the Tutor algorigram uses the same Mermaid layout source as VS Code. Mermaid/Chromium runs only when the graph scope, Thonny theme or settled pane width changes; Thonny then draws the Tutor directly from that single Mermaid SVG geometry on the Tk Canvas, so normal and active node/edge strokes share exactly the same coordinates. Light mode mirrors Mermaid's default palette used by VS Code, while Dark mode remains theme-aware. Tutor stepping toggles only the previously/currently active item IDs, without re-running Mermaid or rescanning the graph;
• Tutor and flowchart requests carry the active document URI explicitly (textDocument.uri plus a compatibility top-level uri), while the LSP normalizes the request through one shared parser;
• Thonny’s native Assistant remains untouched and Python-only; Pseudocode analysis is shown exclusively in the plugin’s Diagnostics tab;
• diagnostics have priority on hover; when the offending token is documented syntax, the tooltip also indicates Ctrl+click → Documentation;
• Ctrl+click on language syntax opens Documentation at that construct, while Ctrl+click on a user symbol keeps LSP go-to-definition;
• Documentation follows the Pseudocode file language, is generated from the core catalogue, and now offers instant weighted search across titles, aliases/syntax, descriptions and concrete examples; complete loop constructions are distinct (Répéter … fois, Répéter … Jusqu'à …, range, stepped range, collection iteration) in every source language;
• the Pseudocode menu, including Documentation, is translated for all 45 Thonny 5 locales, independently from source language;
• Ctrl+Shift+I formats (Ctrl+Shift+F is also accepted). The shared formatter canonically emits French Jusqu'à ... while retaining Jusqu'à ce que ... as accepted input. Analysis is live and automatic, so there is no separate Analyze shortcut;
• the separate Algorigramme tab requests the shared flowchart model from the LSP, uses source-language symbol display_label text instead of canonical English kinds, remains centered in its pane, and exposes ⇩ SVG, ⇩ PNG, ⧉ Mermaid (copy source) and ⇩ Mermaid controls. The shared diagnostic cards use the same icons, colors, borders and clickable line targets as Diagnostics/Tutor. Semantic diagnostics do not suppress a structurally valid graph, but any error-level diagnostic keeps all four export controls visible and disabled; warnings/information remain non-blocking. Only an unavailable AST blocks graph rendering, in which case the same complete localized diagnostic set replaces it. SVG/PNG follow the current Light/Dark theme and SVG uses native text labels. Tutor exposes ⇩ GIF from the already loaded Tutor v2 model in a worker thread; SVG geometry and PNG raster use the same fixed non-responsive Mermaid layout (useMaxWidth=false) so active outlines stay aligned from the top to the bottom of tall diagrams, including decision diamonds. No retrace or per-frame Mermaid render is added; width/theme renders remain cached and coalesced;
• Informations reports Thonny, Python, core, LSP and lexer versions plus LSP state, and shares the same identity block as VS Code: Rodrigo Schwencke, aka Rod2ik; e-mail, repository and documentation are native clickable links;
• F5/Ctrl+R/Run/green triangle on .pseudo / .algo keeps the localized !pseudo <file> execution path; normal Python Run is untouched.
• Pseudocode ↔ Python conversion saves the generated file and immediately opens it in a new Thonny editor tab.
• source-language selection uses a read-only drop-down listing the 14 supported language names together with their ISO 639-1 codes.
• if the pseudo-lsp process or stdio transport fails, the adapter automatically restarts it with bounded backoff and reopens/resynchronizes every tracked Pseudocode document; restart attempts are coalesced, stale responses from replaced server processes are rejected by transport generation, and the manual restart command remains only as a recovery/debug fallback.

The package still installs as one Thonny plugin with normal transitive dependencies; Python itself is not bundled.

What the plugin adds

thonny-pseudocode-i18n is deliberately a thin editor adapter. It does not contain a second parser, semantic analyser or snippet catalogue.

• .pseudo and .algo are registered as one Thonny language: pseudocode;
• the plugin starts the shared pseudo-lsp server over stdio with a small JSON-RPC client;
• diagnostics returned by the server are underlined in the editor and exposed from the dedicated Pseudocode view, with error/warning/information lines coloured red/orange/blue, and an empty diagnostic set displays an explicit all-clear message in the detected Pseudocode language;
• Thonny's native completion popup now opens automatically while typing Pseudocode (Ctrl+Space remains available); rapid typing is debounced before one LSP request, and proposals are filtered/ranked by exact → prefix → contains match instead of showing the whole snippet catalogue;
• localized structural snippets are proposed according to the normal pseudocode-i18n language resolution rules, including distinct range, stepped-range and collection-loop constructions; their details/examples come from the exact shared core documentation card;
• signature help reuses Thonny's existing calltip UI;
• pointer hover waits briefly (450 ms) and then shows the same pedagogical LSP documentation as other IDEs, including localized section labels and every accepted syntax synonym;
• Ctrl+click on a language keyword/connector opens Documentation at that construct; on a user symbol it uses textDocument/definition;
• syntax coloring is driven by pygments-lexer-pseudocode-i18n and mapped to the same native semantic tags Thonny uses for equivalent Python roles;
• a localized root Pseudocode menu organizes run/format/language, conversion, flowcharts, navigation, Documentation, Informations, diagnostics and language-server restart; Run shows F5 / Ctrl+R, Format shows Ctrl+Shift+I / Ctrl+Shift+F, and its UI language follows Thonny, independently from the source pseudocode language; the entire menu is disabled outside an active .pseudo / .algo editor while Thonny’s normal File → Open remains available;
• the dockable Pseudocode view is visible by default and orders Diagnostics → Exécution pas à pas → Documentation → Algorigramme → Informations; Documentation follows the source language, Tutor consumes pseudocode/tutor, and Algorigramme consumes pseudocode/flowchart;
• project-aware diagnostics resolve math, random and existing local .pseudo / .algo modules from the current document/project path, while unknown modules receive a squiggle alongside other diagnostics;
• universal alea() and entalea(a, b) are available through the shared completion/hover/signature-help vocabulary.
• normal Python editing remains handled by Thonny exactly as before.

For example, in a French file:

# language: fr

Fonction carré(x: réel) -> réel:
    Renvoyer x^2
Fin

Afficher carré(3)

start typing a construct such as Pour and Thonny opens the filtered completion popup automatically; Ctrl+Space remains available for an explicit request. The language server resolves the document as French and offers only matching French completions/templates from pseudocode-i18n.

!!! note "Snippets in Thonny 5" The adapter deliberately advertises snippetSupport = false. pseudo-lsp therefore converts canonical LSP snippets to safe plain-text templates before insertion. The same canonical snippet remains a real tabstop snippet in clients such as VS Code or Neovim that advertise snippet support.

Why there is a small LSP client in this plugin

Thonny 5 stable does not yet expose the generic external-language-server proxy API present on the development branch for the next major Thonny version. This plugin therefore owns only the transport/adaptation layer needed by Thonny 5: JSON-RPC framing, document synchronization and mapping responses to Thonny UI components.

The actual language intelligence remains in pseudocode-i18n and pseudocode-i18n-languageserver. When a future stable Thonny exposes a generic LSP proxy, this adapter can be simplified without changing the language or server.

Installation

For a normal end-user installation, install one package from Thonny's plug-in manager (Tools → Manage plug-ins) by searching for thonny-pseudocode-i18n. The equivalent command-line installation is:

python -m pip install 'thonny-pseudocode-i18n>=0.9.12,<0.10'

The package declares Thonny 5, pseudocode-i18n, pseudocode-i18n-languageserver and pygments-lexer-pseudocode-i18n as normal PyPI dependencies, so pip resolves them. Python is not embedded or downloaded by the plugin.

A normal installation does not need the development symlink created by yarn setup. Thonny keeps third-party plug-ins in its private plug-in site-packages directory; the adapter resolves this directory dynamically and exposes it to the pseudo-lsp child process, so the shared LSP/core/lexer installed there remain importable without copying or linking them into the system or user Python site-packages.

Installation for development

Keep the ecosystem repositories as siblings when developing locally:

pseudocode-i18n/
pygments-lexer-pseudocode-i18n/
pseudocode-i18n-languageserver/
thonny-pseudocode-i18n/

Then:

yarn setup
yarn bfc

yarn setup prefers the sibling 0.9.x checkouts and installs this plugin editable. Restart Thonny after installation so its plugin loader discovers thonnycontrib.pseudocode_i18n.

First manual test

Create test.algo:

# language: fr

Fonction double(x: entier) -> entier:
    Renvoyer x * 2
Fin

Afficher double(21)

Open it in Thonny. Then verify:

1. the file is recognized as Pseudocode and colored;
2. introduce an undefined name and check that it is underlined, then use Pseudocode → Diagnostics and click its Lxx link to jump back to the source line;
3. press Ctrl+Space and verify localized completions/templates;
4. Ctrl+click double in the call to jump to its definition;
5. use Pseudocode → Format or Ctrl+Shift+I (also Ctrl+Shift+F);
6. use Pseudocode → Choose language… and verify the read-only list shows language names plus ISO 639-1 codes;
7. convert the file to Python and verify the generated .py file opens automatically in a new tab;
8. open Exécution pas à pas, step through the program and verify the source line, variables, call stack/output and synchronized algorigram update together;
9. open Algorigramme and verify whole-program/symbol scope selection and the rendered preview;
10. switch to a .py or other non-Pseudocode tab and verify that the Pseudocode menu plus all five companion tabs become disabled, then switch back;
11. use Pseudocode → Information and Pseudocode → Navigation → Rename symbol….

Architecture

Thonny 5
  │
  └── thonny-pseudocode-i18n
        ├── file type adapter (.pseudo / .algo)
        ├── thin JSON-RPC/LSP stdio client
        ├── Pygments coloring adapter
        └── Thonny UI adapters
              │
              ▼
          pseudo-lsp
              │
              ▼
        pseudocode-i18n

The language definitions, parser, formatter, diagnostics, semantic index, language detection and snippets stay in pseudocode-i18n. The LSP protocol stays in pseudocode-i18n-languageserver.

Development registration in Thonny 5

yarn setup installs the Python package and also exposes the checkout under Thonny 5's dedicated thonnycontrib plugin directory. Restart Thonny completely after running setup. On Linux, plugin loading can be diagnosed from ~/.config/Thonny/frontend.log.

Development

Useful commands:

yarn setup
yarn test
yarn lint
yarn dev
yarn dev:lan
yarn bfc
yarn zip

package.json is the source of truth for the project version.

License

GNU General Public License version 3 or later (GPL-3.0-or-later).

Run with Thonny

For .pseudo and .algo files, Thonny's normal Run current script, F5, Ctrl+R and green-triangle toolbar button are routed to the same !pseudo <file> CLI execution that can be typed manually in the Shell. This preserves localized Pseudocode diagnostics, source lines and interactive input instead of exposing Python/Thonny backend exceptions. Python files continue to use Thonny's ordinary execution handler unchanged.