selkokielelle: Encoding Accessibility into the Finnish LLM Pipeline

How a minimalist, zero-dependency stack transforms complex officialese into legally compliant Plain Finnish.

A massive, ornate Finnish dictionary being fed into a sleek minimalist printing press, outputting a single, perfectly clear sheet of paper. — Transforming dense bureaucratic text into accessible language requires rigid architectural constraints.

Key Takeaways

The system prompt functions as a linguistic compiler to enforce 50 pages of strict Selkokieli grammatical rules.
A Shadow DOM implementation prevents host website styles from breaking the Chrome extension's accessibility interface.
The project maintains a zero-dependency frontend to ensure the application remains lightweight and easy to deploy.
Strict API constraints eliminate conversational preambles to provide pure, legally compliant text outputs.

The Geometry of Easy Finnish

In Finland, Selkokieli (Plain Finnish) is a rigorous linguistic standard designed for the 750,000 people with cognitive disabilities or language barriers. It is not merely a suggestion to write clearly. It is a strict architectural requirement for Finnish society.

Most artificial intelligence tools equate "simple" with "short." This fails the Selkokieli standard, which demands specific grammatical structures like spelling out numbers one through eleven and outright banning the passive voice. The selkokielelle project tackles this by encoding a 50-page style guide into a single, high-precision system prompt.

A technician in a lab coat shaking complex, jagged Finnish words through a mesh sieve, leaving only smooth, rounded words below. — The system prompt acts as a strict filter, catching complex grammatical structures before they reach the user.

The System Prompt is the Compiler

The core of the application lives in backend/main.py. Here, a FastAPI server acts as a secure proxy between the user and the OpenRouter API. But the real logic layer is the prompt itself. It forces the language model to act as a strict linguistic compiler.

The prompt explicitly forbids the AI from explaining its changes. This "no-preamble" rule ensures the API response is pure text, allowing the frontend to render it immediately without parsing out conversational filler. It also enforces modal verb strength, ensuring the critical difference between "should" and "must" is preserved for legal contexts.

How requests flow through the backend proxy and are transformed by the strict system prompt.

Shadow DOM: The Extension's Safe Harbor

The project extends its utility across the web via a Chrome extension. Injecting user interfaces into arbitrary web pages is notoriously fragile due to CSS collisions. The selkokielelle extension solves this by rendering its translation panel inside a Shadow DOM.

By encapsulating the CSS, the host website's styles cannot leak into the extension. The interface remains pristine and accessible, regardless of the chaotic markup surrounding it.

Architecture without the Anchor

The repository is a masterclass in appropriate technology. There are no heavy JavaScript frameworks, no build tools, and no NPM dependencies on the frontend. It relies entirely on Vanilla HTML, CSS, and JavaScript.

This minimalist stack is paired with a FastAPI backend managed by Systemd and Nginx. It requires no user authentication and logs no personal data. This deliberate architectural choice lowers the barrier to entry for vulnerable users while preventing API abuse through strict IP-based rate limiting.

Standard Finnish	Generic AI Summary	selkokielelle Output
Dense, bureaucratic officialese with passive voice.	Shorter, but often loses critical legal nuances.	Strict adherence to Selkokeskus guidelines.
Uses complex participles and nested clauses.	May use conversational filler and preambles.	Active voice, simple numbers, pure output.
Inaccessible to 750,000 citizens.	Unpredictable grammatical structures.	Legally compliant Plain Finnish.