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.7. 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, 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;
• 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;
• 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 indexes keywords, aliases, connectors and import forms;
• 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). Analysis is live and automatic, so there is no separate Analyze shortcut;
• the separate Algorigramme tab requests the shared flowchart model from the LSP and uses the same asynchronous Mermaid renderer. Width/theme renders are cached and coalesced; Mermaid remains available for export. Tutor width changes are keyed by the real Canvas width and trigger one debounced Mermaid layout refresh, while Tutor stepping itself never launches Mermaid/Chromium rendering;
• Informations reports Thonny, Python, core, LSP and lexer versions plus LSP state;
• 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;
• Ctrl+Space reuses Thonny's completion popup and requests language-aware completions from pseudo-lsp;
• localized structural snippets are proposed according to the normal pseudocode-i18n language resolution rules;
• 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)

press Ctrl+Space while editing to ask pseudo-lsp for completions. The language server resolves the document as French and offers the French 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

The administrator installs one package:

python -m pip install 'thonny-pseudocode-i18n>=0.9.7,<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.

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.