feat(i18n): offer every ISO 639-1 language

The table was thirty languages typed by hand. It is now generated:
utils/generate_languages.py takes the 184 alpha-2 codes from pycountry,
the display names from CLDR through babel, and the writing direction from
CLDR character order. 159 languages carry their endonym; the remaining 25
have no CLDR entry and carry their English ISO name.

That corrects the right-to-left set, which had four entries and needs ten
— dv, ks, ps, sd, ug and yi were simply missed.

Only 29 languages ship an interface catalogue, so the other 155 render in
English until one is filled. make i18n-ui fills app/i18n/ui/ for them, and
make i18n now covers the interface strings as well; neither asks for a
string a shipped catalogue already answers, so hand-written entries stay.

184 entries do not fit on a screen, so the language menu scrolls inside
itself. overscroll-behavior keeps the page behind it from moving once the
list reaches its end.

babel and pycountry are dev dependencies: the generator needs them, the
application does not.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

.claude/.gitignore

@@ -0,0 +1,3 @@
+*
+!.gitignore
+!.settings.json

.claude/settings.json

@@ -0,0 +1,52 @@
+{
+  "permissions": {
+    "allow": [
+      "Read",
+      "Edit",
+      "Write",
+      "Bash(*)",
+      "Read(//tmp/**)",
+      "WebSearch",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "WebFetch(domain:api.github.com)",
+      "WebFetch(domain:docs.docker.com)",
+      "WebFetch(domain:pypi.org)",
+      "WebFetch(domain:docs.cypress.io)",
+      "WebFetch(domain:flask.palletsprojects.com)",
+      "Skill(update-config)",
+      "Skill(update-config:*)"
+    ],
+    "deny": [
+      "Bash(git push --force*)",
+      "Bash(git reset --hard*)",
+      "Bash(rm -rf*)",
+      "Bash(sudo*)"
+    ],
+    "ask": [
+      "Bash(git push*)",
+      "Bash(docker run*)",
+      "Bash(curl*)"
+    ],
+    "additionalDirectories": [
+      "/tmp"
+    ]
+  },
+  "sandbox": {
+    "enabled": true,
+    "autoAllowBashIfSandboxed": true,
+    "filesystem": {
+      "allowWrite": [
+        ".",
+        "/tmp"
+      ],
+      "denyRead": [
+        "~/.ssh",
+        "~/.gnupg",
+        "~/.kube",
+        "~/.aws",
+        "~/.config/gcloud"
+      ]
+    }
+  }
+}

.github/workflows/ci.yml

@@ -1,6 +1,7 @@
 name: CI
 
 on:
+  pull_request:
   push:
     branches:
       - "**"
@@ -9,59 +10,55 @@ on:
 
 permissions:
   contents: read
-  packages: write
 
 jobs:
-  test-and-publish:
+  security:
+    name: Run security workflow
+    uses: ./.github/workflows/security.yml
+    permissions:
+      contents: read
+      packages: read
+      security-events: write
+
+  tests:
+    name: Run test workflow
+    uses: ./.github/workflows/tests.yml
+
+  lint:
+    name: Run lint workflow
+    uses: ./.github/workflows/lint.yml
+    permissions:
+      contents: read
+      security-events: write
+
+  publish:
+    name: Publish image
     runs-on: ubuntu-latest
-    env:
-      PORT: "5000"
+    needs:
+      - security
+      - tests
+      - lint
+    if: github.event_name == 'push'
+    permissions:
+      contents: read
+      packages: write
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-
-      - name: Install Python dependencies
-        run: pip install -r app/requirements.txt
-
-      - name: Prepare app config for CI
-        run: cp app/config.sample.yaml app/config.yaml
-
-      - name: Set up Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: "20"
-          cache: npm
-          cache-dependency-path: app/package.json
-
-      - name: Install Node dependencies
-        working-directory: app
-        run: npm install
-
-      - name: Run Cypress tests
-        uses: cypress-io/github-action@v6
-        with:
-          working-directory: app
-          install: false
-          start: python app.py
-          wait-on: http://127.0.0.1:5000
-          wait-on-timeout: 120
-
       - name: Detect semver tag on current commit
         id: semver
         run: |
           SEMVER_TAG="$(git tag --points-at "$GITHUB_SHA" | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -n 1 || true)"
           if [ -n "$SEMVER_TAG" ]; then
-            echo "found=true" >> "$GITHUB_OUTPUT"
-            echo "raw_tag=$SEMVER_TAG" >> "$GITHUB_OUTPUT"
-            echo "version=${SEMVER_TAG#v}" >> "$GITHUB_OUTPUT"
+            {
+              echo "found=true"
+              echo "raw_tag=$SEMVER_TAG"
+              echo "version=${SEMVER_TAG#v}"
+            } >> "$GITHUB_OUTPUT"
           else
             echo "found=false" >> "$GITHUB_OUTPUT"
           fi

.github/workflows/lint.yml

@@ -0,0 +1,132 @@
+name: Lint
+
+on:
+  workflow_call:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  lint-actions:
+    name: Lint GitHub Actions
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Run actionlint
+        run: docker run --rm -v "$PWD:/repo" -w /repo rhysd/actionlint:latest
+
+  lint-yaml:
+    name: Lint YAML
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install lint dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ".[dev]"
+
+      - name: Run yamllint
+        run: yamllint --strict .
+
+  lint-js:
+    name: Lint JavaScript
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: app/package.json
+
+      - name: Install Node dependencies
+        working-directory: app
+        run: npm install
+
+      - name: Run eslint
+        working-directory: app
+        run: npx eslint .
+
+  lint-shell:
+    name: Lint shell scripts
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Run shellcheck
+        run: docker run --rm -v "$PWD:/mnt" -w /mnt koalaman/shellcheck:stable scripts/*.sh
+
+  lint-python:
+    name: Lint Python
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install lint dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ".[dev]"
+
+      - name: Ruff lint
+        run: ruff check .
+
+      - name: Ruff format check
+        run: ruff format --check .
+
+  lint-docker:
+    name: Lint Dockerfile
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Run hadolint
+        id: hadolint
+        continue-on-error: true
+        uses: hadolint/hadolint-action@2332a7b74a6de0dda2e2221d575162eba76ba5e5
+        with:
+          dockerfile: ./Dockerfile
+          format: sarif
+          output-file: hadolint-results.sarif
+          failure-threshold: warning
+
+      - name: Upload hadolint SARIF
+        if: always() && github.event_name == 'push'
+        uses: github/codeql-action/upload-sarif@v4
+        with:
+          sarif_file: hadolint-results.sarif
+          wait-for-processing: true
+          category: hadolint
+
+      - name: Fail on hadolint warnings
+        if: always()
+        run: python3 utils/check_hadolint_sarif.py hadolint-results.sarif

.github/workflows/security.yml

@@ -0,0 +1,48 @@
+name: Security
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  analyze:
+    name: Run security scan
+    runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
+    permissions:
+      contents: read
+      packages: read
+      security-events: write
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - language: actions
+            build-mode: none
+          - language: javascript-typescript
+            build-mode: none
+          - language: python
+            build-mode: none
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: ${{ matrix.language }}
+          build-mode: ${{ matrix.build-mode }}
+          queries: security-extended,security-and-quality
+
+      - name: Run manual build steps
+        if: matrix.build-mode == 'manual'
+        run: |
+          echo "No manual build is configured for this repository."
+          exit 1
+
+      - name: Perform CodeQL analysis
+        uses: github/codeql-action/analyze@v4
+        with:
+          category: /language:${{ matrix.language }}

.github/workflows/tests.yml

@@ -0,0 +1,194 @@
+name: Tests
+
+on:
+  workflow_call:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test-lint:
+    name: Run lint tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Run lint test suite
+        run: python -m unittest discover -s tests/lint -t .
+
+  test-integration:
+    name: Run integration tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install integration test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install --ignore-installed .
+
+      - name: Run integration test suite
+        run: python -m unittest discover -s tests/integration -t .
+
+  test-unit:
+    name: Run unit tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install unit test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install --ignore-installed .
+
+      - name: Run unit test suite
+        run: python -m unittest discover -s tests/unit -t .
+
+  security-python:
+    name: Run Python security checks
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install security dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install --ignore-installed ".[dev]"
+
+      - name: Run Bandit
+        run: python -m bandit -q -ll -ii -r app main.py
+
+      - name: Export runtime requirements
+        run: python utils/export_runtime_requirements.py > runtime-requirements.txt
+
+      - name: Audit Python runtime dependencies
+        run: python -m pip_audit -r runtime-requirements.txt
+
+  test-security:
+    name: Run security guardrail tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install security test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install --ignore-installed .
+
+      - name: Run security test suite
+        run: python -m unittest discover -s tests/security -t .
+
+  e2e:
+    name: Run end-to-end tests
+    runs-on: ubuntu-latest
+    needs:
+      - test-lint
+      - test-unit
+      - test-integration
+      - security-python
+      - test-security
+    env:
+      FLASK_HOST: "127.0.0.1"
+      FLASK_PORT: "5001"
+      PORT: "5001"
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install Python dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install --ignore-installed .
+
+      - name: Prepare app config for CI
+        run: cp app/config.sample.yaml app/config.yaml
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: app/package.json
+
+      - name: Install Node dependencies
+        working-directory: app
+        run: npm install
+
+      - name: Install Cypress system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            libasound2t64 \
+            libatk-bridge2.0-0 \
+            libatk1.0-0 \
+            libatspi2.0-0t64 \
+            libcups2t64 \
+            libdrm2 \
+            libgbm1 \
+            libglib2.0-0t64 \
+            libgtk-3-0t64 \
+            libnotify4 \
+            libnspr4 \
+            libnss3 \
+            libpango-1.0-0 \
+            libpangocairo-1.0-0 \
+            libxcomposite1 \
+            libxdamage1 \
+            libxfixes3 \
+            libxkbcommon0 \
+            libxrandr2 \
+            libxss1 \
+            libxtst6 \
+            xauth \
+            xvfb
+
+      - name: Run Cypress tests
+        uses: cypress-io/github-action@v6
+        with:
+          working-directory: app
+          install: false
+          start: python app.py
+          wait-on: http://127.0.0.1:5001
+          wait-on-timeout: 120

.gitignore

@@ -1,5 +1,14 @@
 app/config.yaml
+app/i18n/content/
 *__pycache__*
 app/static/cache/*
 .env
-app/cypress/screenshots/*
+app/cypress/screenshots/*
+.ruff_cache/
+app/node_modules/
+app/static/vendor/
+hadolint-results.sarif
+build/
+*.egg-info/
+app/core.*
+.mcp.json

.yamllint

@@ -0,0 +1,23 @@
+---
+# Correctness only. No `extends: default`, so nothing but the rules below runs:
+# the repository predates this linter and its cosmetic findings (indentation,
+# line length, trailing spaces) would be noise nobody acts on.
+#
+# key-duplicates is the rule that earns its keep: PyYAML keeps the last of two
+# identical keys without complaining, so a duplicated entry in a translation
+# catalogue silently drops a translation.
+ignore: |
+  .git/
+  .venv/
+  venv/
+  node_modules/
+  app/node_modules/
+  app/static/vendor/
+  build/
+  .ruff_cache/
+
+rules:
+  key-duplicates: enable
+  octal-values:
+    forbid-implicit-octal: true
+    forbid-explicit-octal: true

AGENTS.md

@@ -0,0 +1,13 @@
+# Agent Instructions
+
+## Pre-Commit Validation
+
+- You MUST run `make test` before every commit whenever the staged change includes at least one file that is not `.md` or `.rst`, unless explicitly instructed otherwise.
+- You MUST commit only after all tests pass.
+- You MUST NOT commit automatically without explicit confirmation from the user.
+
+## Vendor Assets
+
+- Browser vendor assets (Bootstrap, Font Awesome, etc.) are managed via npm.
+- Run `npm install` inside `app/` to populate `app/static/vendor/` before starting the dev server or running e2e tests.
+- Never commit `app/node_modules/` or `app/static/vendor/` — both are gitignored and generated at build time.

CHANGELOG.md

@@ -1,3 +1,35 @@
+## [2.0.0] - 2026-05-18
+
+* * Asset resolution: new probe-first resolver tries a HEAD request and embeds reachable image URLs directly via a new external_url field, falling back to the cache-download path only when the probe fails; broken /static/https://... URLs no longer appear when the source cannot be downloaded
+* Template integration: an asset_src context processor in app.py picks external_url first and url_for(static, cache) second, so base.html.j2, navigation.html.j2, and card.html.j2 never wrap an absolute URL in the static prefix
+* Test coverage: 16 new unit tests cover every probe, cache, and fallback branch; a live integration test exercises https://file.infinito.nexus/assets/img/logo.png to prove the probe-first path works end-to-end without writing to the cache directory
+* Sample configuration: new Infinito.Nexus card in app/config.sample.yaml driven by the canonical file.infinito.nexus asset URL
+* SPOT for build variables: env.example is the single source of truth for IMAGE_NAME and PORT; the Makefile and docker-compose.yml reference both with no defaults and fail loudly when either variable is missing
+* Bootstrap targets: make env and make config materialise .env and app/config.yaml from their checked-in templates without overwriting existing files; build, build-no-cache, up, run-dev, run-prod, dev, prod, and browse depend on both so a fresh checkout runs in a single make invocation
+* Recipe sourcing: Makefile recipes load .env at recipe-execution time via a shared _require_env helper, so a freshly bootstrapped .env is picked up in the same make invocation that created it
+* README: PortUI screenshot added under the title
+* Lint: removed an unused sys import in the live integration test
+
+
+## [1.2.0] - 2026-05-11
+
+* * Navigation behavior: Top-level dropdowns now open reliably on hover and click via Bootstrap, escape the header and navbar overflow clips, and flip between downward and upward based on whether more space is above or below the toggle
+* Compose-driven dependencies: docker-compose runs npm install inside the container on every up and persists node_modules plus static/vendor in named volumes, removing the host-side npm-install step from up, dev, prod, and test-e2e
+* Test coverage: New Cypress specs cover both header and footer dropdown directions, with a Jinja unit test guarding the data-bs-toggle attribute on top-level dropdown toggles
+* Harness configuration: Enabled the Claude Code sandbox with scoped filesystem rules, consolidated the bash allowlist behind a single wildcard, and gitignored local-only state under .claude
+
+
+## [1.1.0] - 2026-03-30
+
+* *CI stabilization and modularization*: Split into reusable workflows (lint, security, tests) with correct permissions for CodeQL and SARIF uploads
+* *Modern Python packaging*: Migration to pyproject.toml and updated Dockerfile using Python 3.12
+* *Improved test coverage*: Added unit, integration, lint, security, and E2E tests using act
+* *Local vendor assets*: Replaced external CDNs with npm-based local asset pipeline
+* *Enhanced build workflow*: Extended Makefile with targets for test, lint, security, and CI plus vendor build process
+* *Frontend fix*: Prevented navbar wrapping and improved layout behavior
+* *Developer guidelines*: Introduced AGENTS.md and CLAUDE.md with enforced pre-commit rules
+
+
 ## [1.0.0] - 2026-02-19
 
 * Official Release🥳

CLAUDE.md

@@ -0,0 +1,5 @@
+# CLAUDE.md
+
+## Startup
+
+You MUST read `AGENTS.md` and follow all instructions in it at the start of every conversation before doing anything else.

Dockerfile

@@ -1,14 +1,20 @@
-# Base image for Python
-FROM python:slim
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    FLASK_HOST=0.0.0.0
+
+# hadolint ignore=DL3008
+RUN apt-get update && apt-get install -y --no-install-recommends nodejs npm && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /tmp/build
+
+COPY pyproject.toml README.md main.py ./
+COPY app ./app
+RUN python -m pip install --no-cache-dir .
 
-# Set the working directory
 WORKDIR /app
-
-# Copy and install dependencies
-COPY app/requirements.txt requirements.txt
-RUN pip install --no-cache-dir -r requirements.txt
-
-# Copy application code
 COPY app/ .
+RUN npm install --prefix /app
 
 CMD ["python", "app.py"]

MIRRORS

@@ -0,0 +1,4 @@
+git@github.com:kevinveenbirkenbach/port-ui.git
+ssh://git@code.infinito.nexus:2201/kevinveenbirkenbach/port-ui.git
+ssh://git@git.veen.world:2201/kevinveenbirkenbach/port-ui.git
+

Makefile

@@ -5,19 +5,63 @@ ifneq (,$(wildcard .env))
     export $(shell sed 's/=.*//' .env)
 endif
 
-# Default port (can be overridden with PORT env var)
-PORT ?= 5000
+PYTHON ?= python3
+ACT ?= act
+
+# Bootstrap the local .env from the checked-in env.example template.
+# Idempotent: leaves an existing .env untouched.
+.PHONY: env
+env:
+	@if [ -f .env ]; then \
+		echo ".env already exists — leaving it alone."; \
+	else \
+		cp env.example .env; \
+		echo "Created .env from env.example — review and adjust."; \
+	fi
+
+# Bootstrap app/config.yaml from the checked-in app/config.sample.yaml
+# template. Idempotent: leaves an existing config.yaml untouched. The
+# Dockerfile COPYs the whole app/ directory at build time, so this file
+# must exist before `make build` / `make up`.
+.PHONY: config
+config:
+	@if [ -f app/config.yaml ]; then \
+		echo "app/config.yaml already exists — leaving it alone."; \
+	else \
+		cp app/config.sample.yaml app/config.yaml; \
+		echo "Created app/config.yaml from app/config.sample.yaml — review and adjust."; \
+	fi
+
+# Build/run recipes source .env at recipe-execution time (not at make
+# parse time) so they work in the same invocation that bootstrapped
+# .env via the `env` prereq. Without this, the inner $$IMAGE_NAME /
+# $$PORT would be empty on the very first `make build` after a fresh
+# checkout — the parse-time `include .env` happens before `env` runs.
+define _require_env
+	if [ ! -f .env ]; then echo "ERROR: .env missing"; exit 1; fi; \
+	. ./.env; \
+	for v in $(1); do \
+		eval "val=\$$$$v"; \
+		[ -n "$$val" ] || { echo "ERROR: $$v is empty in .env (see env.example)"; exit 1; }; \
+	done
+endef
 
-# Default port (can be overridden with PORT env var)
 .PHONY: build
-build:
+build: env config
 	# Build the Docker image.
-	docker build -t application-portfolio .
+	@$(call _require_env,IMAGE_NAME); \
+		docker build -t "$$IMAGE_NAME" .
+
+.PHONY: build-no-cache
+build-no-cache: env config
+	# Build the Docker image without cache.
+	@$(call _require_env,IMAGE_NAME); \
+		docker build --no-cache -t "$$IMAGE_NAME" .
 
 .PHONY: up
-up:
+up: env config
 	# Start the application using docker-compose with build.
-	docker-compose up -d --build
+	docker-compose up -d --build --force-recreate
 
 .PHONY: down
 down:
@@ -27,23 +71,29 @@ down:
 	- docker-compose down
 
 .PHONY: run-dev
-run-dev:
+run-dev: env config config
 	# Run the container in development mode (hot-reload).
-	docker run -d \
-		-p $(PORT):$(PORT) \
-		--name portfolio \
-		-v $(PWD)/app/:/app \
-		-e FLASK_APP=app.py \
-		-e FLASK_ENV=development \
-		application-portfolio
+	@$(call _require_env,IMAGE_NAME PORT); \
+		docker run -d \
+			-p "$$PORT:$$PORT" \
+			--name portfolio \
+			-v "$(PWD)/app/:/app" \
+			-e PORT="$$PORT" \
+			-e TRUSTED_HOSTS="$$TRUSTED_HOSTS" \
+			-e FLASK_APP=app.py \
+			-e FLASK_ENV=development \
+			"$$IMAGE_NAME"
 
 .PHONY: run-prod
-run-prod:
+run-prod: env config config
 	# Run the container in production mode.
-	docker run -d \
-		-p $(PORT):$(PORT) \
-		--name portfolio \
-		application-portfolio
+	@$(call _require_env,IMAGE_NAME PORT); \
+		docker run -d \
+			-p "$$PORT:$$PORT" \
+			--name portfolio \
+			-e PORT="$$PORT" \
+			-e TRUSTED_HOSTS="$$TRUSTED_HOSTS" \
+			"$$IMAGE_NAME"
 
 .PHONY: logs
 logs:
@@ -51,12 +101,12 @@ logs:
 	docker logs -f portfolio
 
 .PHONY: dev
-dev:
+dev: env config
 	# Start the application in development mode using docker-compose.
 	FLASK_ENV=development docker-compose up -d
 
 .PHONY: prod
-prod:
+prod: env config
 	# Start the application in production mode using docker-compose (with build).
 	docker-compose up -d --build
 
@@ -71,12 +121,136 @@ delete:
 	- docker rm -f portfolio
 
 .PHONY: browse
-browse:
-	# Open the application in the browser at http://localhost:$(PORT)
-	chromium http://localhost:$(PORT)
+browse: env
+	# Open the application in the browser at http://localhost:$$PORT
+	@$(call _require_env,PORT); \
+		chromium "http://localhost:$$PORT"
 
-npm-install:
+.PHONY: install
+install:
+	# Install runtime Python dependencies from pyproject.toml.
+	$(PYTHON) -m pip install -e .
+
+.PHONY: install-dev
+install-dev:
+	# Install runtime and developer dependencies from pyproject.toml.
+	$(PYTHON) -m pip install -e ".[dev]"
+
+.PHONY: i18n
+i18n: env config
+	# Fill missing content translations in app/i18n/content/ via LibreTranslate.
+	@$(call _require_env,LIBRETRANSLATE_URL); \
+		$(PYTHON) utils/i18n_sync.py \
+			--url "$$LIBRETRANSLATE_URL" \
+			--api-key "$$LIBRETRANSLATE_API_KEY"
+
+.PHONY: i18n-ui
+i18n-ui: env
+	# Fill missing interface translations in app/i18n/ui/ via LibreTranslate.
+	@$(call _require_env,LIBRETRANSLATE_URL); \
+		$(PYTHON) utils/i18n_sync.py \
+			--catalog ui \
+			--url "$$LIBRETRANSLATE_URL" \
+			--api-key "$$LIBRETRANSLATE_API_KEY"
+
+.PHONY: lint-actions
+lint-actions:
+	# Lint GitHub Actions workflows.
+	docker run --rm -v "$$PWD:/repo" -w /repo rhysd/actionlint:latest
+
+.PHONY: lint-python
+lint-python: install-dev
+	# Run Python lint and format checks.
+	$(PYTHON) -m ruff check .
+	$(PYTHON) -m ruff format --check .
+
+.PHONY: lint-docker
+lint-docker:
+	# Lint the Dockerfile.
+	docker run --rm -i hadolint/hadolint < Dockerfile
+
+.PHONY: lint-yaml
+lint-yaml: install-dev
+	# Lint YAML for duplicate keys and ambiguous scalars (see .yamllint).
+	$(PYTHON) -m yamllint --strict .
+
+.PHONY: lint-js
+lint-js: node-deps
+	# Lint the browser and Cypress JavaScript.
+	cd app && env -u ELECTRON_RUN_AS_NODE npx eslint .
+
+.PHONY: lint-shell
+lint-shell:
+	# Lint the shell scripts.
+	docker run --rm -v "$$PWD:/mnt" -w /mnt koalaman/shellcheck:stable scripts/*.sh
+
+.PHONY: test-lint
+test-lint:
+	# Run lint guardrail tests.
+	$(PYTHON) -m unittest discover -s tests/lint -t .
+
+.PHONY: test-integration
+test-integration: install
+	# Run repository integration tests.
+	$(PYTHON) -m unittest discover -s tests/integration -t .
+
+.PHONY: test-unit
+test-unit: install
+	# Run repository unit tests.
+	$(PYTHON) -m unittest discover -s tests/unit -t .
+
+.PHONY: test-security
+test-security: install
+	# Run repository security guardrail tests.
+	$(PYTHON) -m unittest discover -s tests/security -t .
+
+.PHONY: lint
+lint: lint-actions lint-python lint-yaml lint-js lint-docker lint-shell test-lint
+	# Run the full lint suite.
+
+.PHONY: security
+security: install-dev test-security
+	# Run security checks.
+	$(PYTHON) -m bandit -q -ll -ii -r app main.py
+	$(PYTHON) utils/export_runtime_requirements.py > /tmp/portfolio-runtime-requirements.txt
+	$(PYTHON) -m pip_audit -r /tmp/portfolio-runtime-requirements.txt
+
+.PHONY: node-deps
+node-deps:
+	# Install the Cypress binary and the browser vendor assets into app/.
 	cd app && npm install
 
-test: npm-install
-	cd app && npx cypress run --spec "cypress/e2e/**/*.spec.js"
+.PHONY: test-e2e
+test-e2e: env config node-deps
+	# Run Cypress against a locally started Flask app — no act, no runner image.
+	@$(call _require_env,PORT); \
+		PORT="$$PORT" PYTHON="$(PYTHON)" scripts/run-e2e.sh
+
+.PHONY: test-e2e-act
+test-e2e-act:
+	# Run the CI end-to-end job through act (stop portfolio container to free port first).
+	-docker stop portfolio 2>/dev/null || true
+	$(ACT) workflow_dispatch -W .github/workflows/tests.yml -j e2e
+	-docker start portfolio 2>/dev/null || true
+
+.PHONY: test-workflow
+test-workflow:
+	# Run the GitHub test workflow locally via act.
+	$(ACT) workflow_dispatch -W .github/workflows/tests.yml
+
+.PHONY: lint-workflow
+lint-workflow:
+	# Run the GitHub lint workflow locally via act.
+	$(ACT) workflow_dispatch -W .github/workflows/lint.yml
+
+.PHONY: quality
+quality: lint-workflow test-workflow
+	# Run the GitHub lint and test workflows locally via act.
+
+.PHONY: ci
+ci: lint security test-unit test-integration test-e2e
+	# Run the local CI suite.
+
+.PHONY: test
+test: ci
+	# Run the full validation suite.

README.md

@@ -1,12 +1,11 @@
 # PortUI 🖥️✨
 
-[![GitHub Sponsors](https://img.shields.io/badge/Sponsor-GitHub%20Sponsors-blue?logo=github)](https://github.com/sponsors/kevinveenbirkenbach)  
-[![Patreon](https://img.shields.io/badge/Support-Patreon-orange?logo=patreon)](https://www.patreon.com/c/kevinveenbirkenbach)  
-[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20me%20a%20Coffee-Funding-yellow?logo=buymeacoffee)](https://buymeacoffee.com/kevinveenbirkenbach)  
-[![PayPal](https://img.shields.io/badge/Donate-PayPal-blue?logo=paypal)](https://s.veen.world/paypaldonate)
+[![GitHub Sponsors](https://img.shields.io/badge/Sponsor-GitHub%20Sponsors-blue?logo=github)](https://github.com/sponsors/kevinveenbirkenbach) [![Patreon](https://img.shields.io/badge/Support-Patreon-orange?logo=patreon)](https://www.patreon.com/c/kevinveenbirkenbach) [![Buy Me a Coffee](https://img.shields.io/badge/Buy%20me%20a%20Coffee-Funding-yellow?logo=buymeacoffee)](https://buymeacoffee.com/kevinveenbirkenbach) [![PayPal](https://img.shields.io/badge/Donate-PayPal-blue?logo=paypal)](https://s.veen.world/paypaldonate)
 
 A lightweight, Docker-powered portfolio/landing-page generator—fully customizable via YAML! Showcase your projects, skills, and online presence in minutes.  
 
+![PortUI screenshot](assets/img/screenshot.png)
+
 > 🚀 You can also pair PortUI with JavaScript for sleek, web-based desktop-style interfaces.  
 > 💻 Example in action: [CyMaIS.Cloud](https://cymais.cloud/) (demo)  
 > 🌐 Another live example: [veen.world](https://www.veen.world/) (Kevin’s personal site)
@@ -23,6 +22,8 @@ A lightweight, Docker-powered portfolio/landing-page generator—fully customiza
   Auto-cache assets for lightning-fast loading.  
 - **Responsive Design**  
   Built on Bootstrap; looks great on desktop, tablet & mobile.  
+- **184 Languages**  
+  Every ISO 639-1 code, browser-negotiated, RTL-aware, with machine translation for your own content.  
 - **YAML-Driven**  
   All content & structure defined in a simple `config.yaml`.  
 - **CLI Control**  
@@ -140,12 +141,60 @@ company:
 
 ---
 
+## 🌍 Languages
+
+Every ISO 639-1 language — all 184 two-letter codes — has a URL, a display
+name in its own script and a writing direction. The interface ships translated
+for 29 of them; the rest fall back to English string by string until a
+catalogue is filled. `/` serves the best match for the visitor's
+`Accept-Language` header, `/<code>/` forces one, and a switcher in the navbar
+lists them all. The ten right-to-left languages get `dir="rtl"` and Bootstrap's RTL
+stylesheet automatically.
+
+Translations live in two catalogues, both keyed by the English source string:
+
+| Path | Tracked | Holds |
+| --- | --- | --- |
+| `app/i18n/ui/<code>.yaml` | yes | Interface strings. Shipped for 29 languages; English is the source and has no file. |
+| `app/i18n/content/<code>.yaml` | no | Your `config.yaml` prose, generated per deployment. |
+
+A string with no catalogue entry falls back to English, so a half-filled
+catalogue degrades instead of breaking.
+
+Fill the content catalogues from a [LibreTranslate](https://libretranslate.com/)
+instance — set `LIBRETRANSLATE_URL` in `.env`, then:
+
+```bash
+make i18n
+```
+
+This fills the interface strings of the languages that ship no catalogue as
+well. Existing entries are never overwritten, and a string the shipped
+catalogue already covers is never requested, so corrections you make by hand
+survive later runs. Only prose (`description`, `text`, `warning`, `info`, `subtitel`) is
+filled automatically; `name` and `title` are left to you, because a machine
+cannot tell the menu label "Pictures" from the brand "Mastodon". Write those
+into the content catalogue yourself when you want them translated.
+
+---
+
 ## 🚢 Production Deployment
 
 * Use a reverse proxy (NGINX/Apache).
 * Secure with SSL/TLS.
 * Swap to a production database if needed.
 
+Because every page carries a canonical URL and 184 `hreflang` alternates, two
+details of the proxy setup now matter:
+
+* **Set `TRUSTED_HOSTS`** in `.env` to your public hostname(s), comma-separated.
+  Left empty, the app reflects whatever `Host` header arrives into its canonical,
+  `hreflang` and redirect URLs — so a shared cache in front of it can be made to
+  store a redirect pointing somewhere else.
+* **Have the proxy send `X-Forwarded-Proto`.** Without it the app cannot know TLS
+  terminated upstream and every canonical URL claims `http://`. `X-Forwarded-Host`
+  is deliberately *not* trusted; set `Host` to the public name instead.
+
 ---
 
 ## 📜 License

app/__init__.py

@@ -0,0 +1 @@
+"""Portfolio UI web application package."""

app/app.py

@@ -1,18 +1,34 @@
-import os
-from flask import Flask, render_template
-import yaml
-import requests
-from utils.configuration_resolver import ConfigurationResolver
-from utils.cache_manager import CacheManager
-from utils.compute_card_classes import compute_card_classes
 import logging
-logging.basicConfig(level=logging.DEBUG)
-FLASK_ENV = os.getenv("FLASK_ENV", "production")
-FLASK_PORT = int(os.getenv("PORT", 5000))
-print(f"🔧 Starting app on port {FLASK_PORT}, FLASK_ENV={FLASK_ENV}")
+import os
 
-from flask import Flask, render_template, current_app
+import requests
+import yaml
+from flask import Flask, current_app, make_response, render_template, request, url_for
 from markupsafe import Markup
+from werkzeug.middleware.proxy_fix import ProxyFix
+
+try:
+    from app.utils import i18n
+    from app.utils.asset_resolver import asset_src, resolve_asset_cache
+    from app.utils.cache_manager import CacheManager
+    from app.utils.compute_card_classes import compute_card_classes
+    from app.utils.configuration_resolver import ConfigurationResolver
+except ImportError:  # pragma: no cover - supports running from the app/ directory.
+    from utils.asset_resolver import asset_src, resolve_asset_cache
+    from utils.cache_manager import CacheManager
+    from utils.compute_card_classes import compute_card_classes
+    from utils.configuration_resolver import ConfigurationResolver
+
+    from utils import i18n
+
+TRANSLATED_SECTIONS = ("cards", "company", "navigation", "platform")
+
+logging.basicConfig(level=logging.DEBUG)
+
+FLASK_ENV = os.getenv("FLASK_ENV", "production")
+FLASK_HOST = os.getenv("FLASK_HOST", "127.0.0.1")
+FLASK_PORT = int(os.getenv("FLASK_PORT", os.getenv("PORT", 5000)))
+print(f"Starting app on {FLASK_HOST}:{FLASK_PORT}, FLASK_ENV={FLASK_ENV}")
 
 # Initialize the CacheManager
 cache_manager = CacheManager()
@@ -20,10 +36,11 @@ cache_manager = CacheManager()
 # Clear cache on startup
 cache_manager.clear_cache()
 
+
 def load_config(app):
     """Load and resolve the configuration from config.yaml."""
-    with open("config.yaml", "r") as f:
-        config = yaml.safe_load(f)
+    with open("config.yaml", "r", encoding="utf-8") as handle:
+        config = yaml.safe_load(handle)
 
     if config.get("nasa_api_key"):
         app.config["NASA_API_KEY"] = config["nasa_api_key"]
@@ -31,50 +48,65 @@ def load_config(app):
     resolver = ConfigurationResolver(config)
     resolver.resolve_links()
     app.config.update(resolver.get_config())
+    app.config["TRANSLATED_CONFIG"] = {}
+    i18n.clear_catalogs()
+
 
 def cache_icons_and_logos(app):
-    """Cache all icons and logos to local files, mit Fallback auf source."""
+    """Resolve every icon/logo/favicon to either a local cache path or
+    an external URL (see ``resolve_asset_cache``)."""
     for card in app.config["cards"]:
-        icon = card.get("icon", {})
-        if icon.get("source"):
-            cached = cache_manager.cache_file(icon["source"])
-            # Fallback: wenn cache_file None liefert, nutze weiterhin source
-            icon["cache"] = cached or icon["source"]
+        icon = card.get("icon")
+        if icon:
+            resolve_asset_cache(icon, cache_manager)
 
-    # Company-Logo
-    company_logo = app.config["company"]["logo"]
-    cached = cache_manager.cache_file(company_logo["source"])
-    company_logo["cache"] = cached or company_logo["source"]
-
-    # Platform Favicon
-    favicon = app.config["platform"]["favicon"]
-    cached = cache_manager.cache_file(favicon["source"])
-    favicon["cache"] = cached or favicon["source"]
-
-    # Platform Logo
-    platform_logo = app.config["platform"]["logo"]
-    cached = cache_manager.cache_file(platform_logo["source"])
-    platform_logo["cache"] = cached or platform_logo["source"]
+    resolve_asset_cache(app.config["company"]["logo"], cache_manager)
+    resolve_asset_cache(app.config["platform"]["favicon"], cache_manager)
+    resolve_asset_cache(app.config["platform"]["logo"], cache_manager)
 
 
 # Initialize Flask app
 app = Flask(__name__)
 
+app.jinja_options = {**app.jinja_options, "autoescape": True}
+
+app.wsgi_app = ProxyFix(app.wsgi_app, x_proto=1)
+
+
+def trusted_hosts(raw):
+    """Parse a comma-separated host list, or None when nothing is configured.
+
+    Args:
+        raw: the ``TRUSTED_HOSTS`` value, possibly empty.
+    """
+    hosts = [host.strip() for host in raw.split(",") if host.strip()]
+    return hosts or None
+
+
+app.config["TRUSTED_HOSTS"] = trusted_hosts(os.getenv("TRUSTED_HOSTS", ""))
+
 # Load configuration and cache assets on startup
 load_config(app)
 cache_icons_and_logos(app)
 
+
 @app.context_processor
 def utility_processor():
     def include_svg(path):
-        full_path = os.path.join(current_app.root_path, 'static', path)
+        full_path = os.path.join(current_app.root_path, "static", path)
         try:
-            with open(full_path, 'r', encoding='utf-8') as f:
-                svg = f.read()
-            return Markup(svg)
-        except IOError:
-            return Markup(f'<!-- SVG not found: {path} -->')
-    return dict(include_svg=include_svg)
+            with open(full_path, "r", encoding="utf-8") as handle:
+                svg = handle.read()
+            # Trusted local SVG asset shipped with the application package.
+            return Markup(svg)  # nosec B704
+        except OSError:
+            return ""
+
+    def template_asset_src(asset):
+        return asset_src(asset, lambda filename: url_for("static", filename=filename))
+
+    return dict(include_svg=include_svg, asset_src=template_asset_src)
+
 
 @app.before_request
 def reload_config_in_dev():
@@ -83,35 +115,84 @@ def reload_config_in_dev():
         load_config(app)
         cache_icons_and_logos(app)
 
-@app.route('/')
-def index():
-    """Render the main index page."""
-    cards = app.config["cards"]
-    lg_classes, md_classes = compute_card_classes(cards)
-    # fetch NASA APOD URL only if key present
-    apod_bg = None
+
+def translated_config(lang):
+    """Return the configuration sections translated into ``lang``, memoized.
+
+    The memo is dropped by ``load_config``, so a development reload picks up
+    edited content on the next request.
+    """
+    memo = app.config["TRANSLATED_CONFIG"]
+    if lang not in memo:
+        source = {section: app.config[section] for section in TRANSLATED_SECTIONS}
+        memo[lang] = i18n.translate_tree(source, lang)
+    return memo[lang]
+
+
+def apod_background():
+    """Return today's NASA APOD image URL, or None when unavailable."""
     api_key = app.config.get("NASA_API_KEY")
-    if api_key:
+    if not api_key:
+        return None
+
+    try:
         resp = requests.get(
             "https://api.nasa.gov/planetary/apod",
-            params={"api_key": api_key}
+            params={"api_key": api_key},
+            timeout=10,
         )
-        if resp.ok:
-            data = resp.json()
-            # only use if it's an image
-            if data.get("media_type") == "image":
-                apod_bg = data.get("url")
+    except requests.RequestException:
+        logging.warning("APOD lookup failed", exc_info=True)
+        return None
+
+    if not resp.ok:
+        return None
+
+    data = resp.json()
+    return data.get("url") if data.get("media_type") == "image" else None
+
+
+def render_index(lang):
+    """Render the index page in ``lang``."""
+    config = translated_config(lang)
+    cards = config["cards"]
+    lg_classes, md_classes = compute_card_classes(cards)
 
     return render_template(
         "pages/index.html.j2",
         cards=cards,
-        company=app.config["company"],
-        navigation=app.config["navigation"],
-        platform=app.config["platform"],
+        company=config["company"],
+        navigation=config["navigation"],
+        platform=config["platform"],
         lg_classes=lg_classes,
         md_classes=md_classes,
-        apod_bg=apod_bg
+        apod_bg=apod_background(),
+        lang=lang,
+        lang_dir=i18n.direction(lang),
+        languages=i18n.LANGUAGES,
+        ui_strings=i18n.ui_strings(lang),
+        t=lambda source: i18n.catalog(lang).get(source, source),
     )
 
+
+@app.route("/")
+def index():
+    """Render the index page in the language the browser asks for."""
+    response = make_response(render_index(i18n.negotiate(request.accept_languages)))
+    response.headers["Vary"] = "Accept-Language"
+    return response
+
+
+@app.route(f"/<any({','.join(i18n.LANGUAGES)}):lang>/")
+def localized_index(lang):
+    """Render the index page in an explicitly requested language."""
+    return render_index(lang)
+
+
 if __name__ == "__main__":
-    app.run(debug=(FLASK_ENV == "development"), host="0.0.0.0", port=FLASK_PORT)
+    app.run(
+        debug=(FLASK_ENV == "development"),
+        host=FLASK_HOST,
+        port=FLASK_PORT,
+        use_reloader=False,
+    )

app/config.sample.yaml

@@ -198,7 +198,16 @@ accounts:
     url: https://s.veen.world/cloud
 
 cards:
-- icon: 
+- icon:
+    source: https://file.infinito.nexus/assets/img/logo.png
+  title: Infinito.Nexus
+  text: Open-source self-hosting stack — one-click deployable FOSS web apps with
+    shared identity, asset, and observability services. The platform that hosts
+    this site, including the dashboard you are looking at.
+  url: https://infinito.nexus
+  link_text: infinito.nexus
+  iframe: true
+- icon:
     source: https://cloud.veen.world/s/logo_agile_coach_512x512/download
   title: Agile Coach
   text: I lead agile transformations and improve team dynamics through Scrum, DevOps,

app/cypress/e2e/i18n.spec.js

@@ -0,0 +1,243 @@
+// cypress/e2e/i18n.spec.js
+
+const GERMAN_BROWSER = { headers: { 'Accept-Language': 'de-DE,de;q=0.9,en;q=0.8' } };
+
+describe('Language negotiation', () => {
+  it('serves English to an English browser', () => {
+    cy.visit('/', { headers: { 'Accept-Language': 'en-US,en;q=0.9' } });
+    cy.get('html').should('have.attr', 'lang', 'en');
+    cy.get('footer.footer a.iframe-link').should('contain.text', 'Imprint');
+  });
+
+  it('serves German to a German browser', () => {
+    cy.visit('/', GERMAN_BROWSER);
+    cy.get('html').should('have.attr', 'lang', 'de');
+    cy.get('footer.footer a.iframe-link').should('contain.text', 'Impressum');
+  });
+
+  it('falls back to English for an unsupported browser language', () => {
+    cy.visit('/', { headers: { 'Accept-Language': 'xx-XX' } });
+    cy.get('html').should('have.attr', 'lang', 'en');
+  });
+
+  it('lets the URL prefix override the browser language', () => {
+    cy.visit('/fr/', GERMAN_BROWSER);
+    cy.get('html').should('have.attr', 'lang', 'fr');
+    cy.get('footer.footer a.iframe-link').should('contain.text', 'Mentions légales');
+  });
+
+  it('rejects an unsupported language code', () => {
+    cy.request({ url: '/xx/', failOnStatusCode: false })
+      .its('status')
+      .should('eq', 404);
+  });
+
+  it('does not turn unrelated single-segment paths into redirects', () => {
+    ['/robots.txt', '/favicon.ico', '/sitemap.xml'].forEach(path => {
+      cy.request({ url: path, failOnStatusCode: false, followRedirect: false })
+        .its('status')
+        .should('eq', 404);
+    });
+  });
+
+  it('marks the negotiated route as varying by language', () => {
+    cy.request('/')
+      .its('headers.vary')
+      .should('contain', 'Accept-Language');
+  });
+});
+
+describe('Language switcher', () => {
+  beforeEach(() => {
+    cy.viewport(1280, 720);
+    cy.visit('/en/');
+  });
+
+  it('names the active language and offers every ISO 639-1 code', () => {
+    cy.get('#navbarDropdownLanguage')
+      .should('have.attr', 'data-bs-toggle', 'dropdown')
+      .and('contain.text', 'English');
+
+    cy.get('#navbarDropdownLanguage')
+      .parent('.nav-item')
+      .find('> .dropdown-menu a.dropdown-item')
+      .should('have.length', 184);
+  });
+
+  it('marks the active language', () => {
+    cy.get('#navbarDropdownLanguage').click();
+    cy.get('.dropdown-menu a.dropdown-item.active[hreflang="en"]').should('exist');
+  });
+
+  it('navigates to the chosen language', () => {
+    cy.get('#navbarDropdownLanguage').click();
+    cy.get('.dropdown-menu a.dropdown-item[hreflang="de"]')
+      .should('have.text', 'Deutsch')
+      .click();
+
+    cy.url().should('match', /\/de\/$/);
+    cy.get('html').should('have.attr', 'lang', 'de');
+  });
+});
+
+describe('Translated interface strings', () => {
+  it('translates the strings rendered by the templates', () => {
+    cy.visit('/de/');
+    cy.get('#dynamicCopyButton').should('have.text', 'Kopieren');
+    cy.get('#dynamicChildrenSection h6').should('have.text', 'Optionen:');
+    cy.get('#dynamicAlternativesSection h6').should('have.text', 'Alternativen:');
+    cy.get('.modal-footer button').should('have.text', 'Schließen');
+  });
+
+  it('exposes the catalogue to client-side code', () => {
+    cy.visit('/de/');
+    cy.window().its('I18N').should('deep.include', {
+      Open: 'Öffnen',
+      'Open Link': 'Link öffnen',
+      'Identifier copied to clipboard!': 'Kennung in die Zwischenablage kopiert!',
+    });
+  });
+
+  it('leaves the catalogue untranslated in the source language', () => {
+    cy.visit('/en/');
+    cy.window().its('I18N').should('deep.include', { Open: 'Open' });
+  });
+});
+
+describe('Strings translated by modal.js', () => {
+  const item = {
+    name: 'Test Item',
+    identifier: 'ABC123',
+    icon: { class: 'fa fa-test' },
+    alternatives: [
+      { name: 'Alt One', identifier: 'ALT1', icon: { class: 'fa fa-alt1' } },
+    ],
+  };
+
+  beforeEach(() => {
+    cy.visit('/de/');
+    cy.window().then(win => {
+      cy.stub(win.navigator.clipboard, 'writeText').resolves();
+      cy.stub(win, 'alert');
+    });
+  });
+
+  it('translates the button of a list entry', () => {
+    cy.window().invoke('openDynamicPopup', item);
+    cy.get('#dynamicAlternativesList button').should('have.text', 'Öffnen');
+  });
+
+  it('translates the link label when the entry has no description', () => {
+    cy.window().invoke('openDynamicPopup', {
+      ...item,
+      url: 'https://example.com',
+      description: null,
+    });
+    cy.get('#dynamicModalLinkHref').should('have.text', 'Link öffnen');
+  });
+
+  it('translates the clipboard confirmation', () => {
+    cy.window().invoke('openDynamicPopup', item);
+    cy.get('#dynamicCopyButton').click();
+    cy.window()
+      .its('alert')
+      .should('have.been.calledWith', 'Kennung in die Zwischenablage kopiert!');
+  });
+});
+
+describe('Right-to-left languages', () => {
+  it('flips the document and loads the RTL stylesheet', () => {
+    cy.visit('/ar/');
+    cy.get('html').should('have.attr', 'dir', 'rtl');
+    cy.get('link[href*="bootstrap.rtl.min.css"]').should('exist');
+    cy.get('link[href*="vendor/bootstrap/css/bootstrap.min.css"]').should('not.exist');
+    cy.get('body').should('have.css', 'direction', 'rtl');
+  });
+
+  it('keeps left-to-right languages on the default stylesheet', () => {
+    cy.visit('/en/');
+    cy.get('html').should('have.attr', 'dir', 'ltr');
+    cy.get('link[href*="bootstrap.rtl.min.css"]').should('not.exist');
+  });
+
+  it('actually serves the RTL stylesheet it links to', () => {
+    cy.visit('/ar/');
+    cy.get('link[href*="bootstrap.rtl.min.css"]')
+      .should('have.attr', 'href')
+      .then(href => {
+        cy.request(href).its('status').should('eq', 200);
+      });
+  });
+});
+
+describe('Translated interface details', () => {
+  it('translates the strings only a screen reader sees', () => {
+    cy.visit('/de/');
+
+    cy.get('#dynamicModal .btn-close').should('have.attr', 'aria-label', 'Schließen');
+  });
+
+  it('translates the alert headings', () => {
+    cy.visit('/fr/');
+
+    cy.get('#dynamicModalWarning h5').should('contain.text', 'Avertissement');
+    cy.get('#dynamicModalInfo h5').should('contain.text', 'Informations');
+  });
+
+  it('translates the language switcher tooltip', () => {
+    cy.visit('/de/');
+
+    cy.get('#navbarDropdownLanguage').should('have.attr', 'title', 'Sprache');
+  });
+
+  it('tags each switcher entry with its own language', () => {
+    cy.visit('/en/');
+
+    cy.get('.dropdown-menu a.dropdown-item[hreflang="ja"]').should(
+      'have.attr',
+      'lang',
+      'ja',
+    );
+  });
+
+  it('scrolls inside the language menu instead of past the page', () => {
+    cy.viewport(1280, 720);
+    cy.visit('/en/');
+    cy.get('#navbarDropdownLanguage').click();
+
+    cy.get('.dropdown-menu.language-menu').should($menu => {
+      const menu = $menu[0];
+      expect(menu.scrollHeight, 'taller than it shows').to.be.greaterThan(
+        menu.clientHeight,
+      );
+      expect(menu.getBoundingClientRect().height).to.be.lessThan(720);
+      expect(getComputedStyle(menu).overflowY).to.eq('auto');
+    });
+  });
+
+  it('offers the switcher in the header only', () => {
+    cy.viewport(1280, 720);
+    cy.visit('/en/');
+
+    cy.get('#navbarNavheader #navbarDropdownLanguage').should('exist');
+    cy.get('#navbarNavfooter #navbarDropdownLanguage').should('not.exist');
+  });
+});
+
+describe('Search engine metadata', () => {
+  beforeEach(() => {
+    cy.visit('/de/');
+  });
+
+  it('declares an alternate for every language plus a default', () => {
+    cy.get('link[rel="alternate"][hreflang]').should('have.length', 185);
+    cy.get('link[rel="alternate"][hreflang="x-default"]').should('exist');
+    cy.get('link[rel="alternate"][hreflang="ja"]')
+      .should('have.attr', 'href')
+      .and('match', /\/ja\/$/);
+  });
+
+  it('points the canonical URL at the language actually served', () => {
+    cy.get('link[rel="canonical"]').should('have.attr', 'href').and('match', /\/de\/$/);
+  });
+});

app/cypress/e2e/injection.spec.js

@@ -0,0 +1,197 @@
+// cypress/e2e/injection.spec.js
+
+describe('Untrusted content in the modal', () => {
+  const base = {
+    name: 'Test Item',
+    identifier: 'ABC123',
+    icon: { class: 'fa fa-test' },
+  };
+
+  beforeEach(() => {
+    cy.visit('/');
+    cy.window().then(win => {
+      cy.stub(win.navigator.clipboard, 'writeText').resolves();
+      cy.stub(win, 'alert');
+    });
+  });
+
+  function open(item = {}) {
+    cy.window().invoke('openDynamicPopup', { ...base, ...item });
+  }
+
+  describe('markdown rendered into innerHTML', () => {
+    it('strips a plain script URL', () => {
+      open({
+        warning: '[click me](javascript:window.__xss = true)',
+        info: '![x](data:text/html;base64,PHNjcmlwdD4=)',
+      });
+
+      cy.get('#dynamicModalWarningText').find('a').should('not.exist');
+      cy.get('#dynamicModalWarningText').should('contain.text', 'click me');
+      cy.get('#dynamicModalInfoText').find('img').should('not.exist');
+      cy.window().should('not.have.property', '__xss');
+    });
+
+    it('strips a script URL hidden behind character references', () => {
+      open({
+        warning:
+          '[a](javascript:window.__xss=1) [b](javascript:window.__xss=1)',
+        info: '[c](java	script:window.__xss=1) [d](java
script:window.__xss=1)',
+      });
+
+      cy.get('#dynamicModalWarningText').find('a').should('not.exist');
+      cy.get('#dynamicModalInfoText').find('a').should('not.exist');
+      cy.window().should('not.have.property', '__xss');
+    });
+
+    it('strips a script URL written as a reference-style link', () => {
+      open({
+        warning: '[click me][ref]\n\n[ref]: javascript:window.__xss=1',
+      });
+
+      cy.get('#dynamicModalWarningText').find('a').should('not.exist');
+      cy.window().should('not.have.property', '__xss');
+    });
+
+    it('neutralises raw HTML', () => {
+      open({
+        warning: '<img src=x onerror="window.__xss = true">',
+        info: '<a href="javascript:window.__xss = true">x</a>',
+      });
+
+      cy.get('#dynamicModalWarningText').find('img').should('not.exist');
+      cy.get('#dynamicModalWarningText').should('contain.text', 'onerror');
+      cy.get('#dynamicModalInfoText').find('a').should('not.exist');
+      cy.window().should('not.have.property', '__xss');
+    });
+
+    it('neutralises raw HTML used as the text of a stripped link', () => {
+      open({ warning: '[<img src=x onerror="window.__xss = true">](javascript:bad)' });
+
+      cy.get('#dynamicModalWarningText').find('img').should('not.exist');
+      cy.window().should('not.have.property', '__xss');
+    });
+
+    it('keeps ordinary markdown', () => {
+      open({ warning: 'See [Matrix](https://matrix.org/) and **mind** this' });
+
+      cy.get('#dynamicModalWarningText')
+        .find('a')
+        .should('have.attr', 'href', 'https://matrix.org/');
+      cy.get('#dynamicModalWarningText').find('strong').should('have.text', 'mind');
+    });
+  });
+
+  describe('values interpolated outside markdown', () => {
+    it('does not treat the name or the icon class as markup', () => {
+      open({
+        name: '<img src=x onerror="window.__xss = true">',
+        icon: { class: 'fa" onmouseover="window.__xss = true' },
+        alternatives: [
+          {
+            name: '<img src=y onerror="window.__xss = true">',
+            identifier: 'ALT1',
+            icon: { class: 'fa-alt' },
+          },
+        ],
+      });
+
+      cy.get('#dynamicModalLabel').find('img').should('not.exist');
+      cy.get('#dynamicModalLabel').should('contain.text', 'onerror');
+      cy.get('#dynamicAlternativesList').find('img').should('not.exist');
+      cy.get('#dynamicAlternativesList').should('contain.text', 'onerror');
+      cy.window().should('not.have.property', '__xss');
+    });
+  });
+
+  describe('the link the modal offers', () => {
+    it('drops a URL that uses an unsafe scheme', () => {
+      open({ url: 'javascript:window.__xss = true', description: 'Bad' });
+
+      cy.get('#dynamicModalLinkHref').should('not.have.attr', 'href');
+      cy.get('#dynamicModalLinkHref').should('have.text', 'Bad');
+      cy.window().should('not.have.property', '__xss');
+    });
+
+    it('keeps an ordinary URL', () => {
+      open({ url: 'https://example.com', description: 'Good' });
+
+      cy.get('#dynamicModalLinkHref').should(
+        'have.attr',
+        'href',
+        'https://example.com',
+      );
+    });
+
+    it('keeps a mailto URL', () => {
+      open({ url: 'mailto:kevin@veen.world', description: 'Write' });
+
+      cy.get('#dynamicModalLinkHref').should(
+        'have.attr',
+        'href',
+        'mailto:kevin@veen.world',
+      );
+    });
+
+    it('restores the link after a popup whose URL was dropped', () => {
+      open({ url: 'javascript:window.__xss = true', description: 'Bad' });
+      cy.get('#dynamicModalLinkHref').should('not.have.attr', 'href');
+
+      open({ url: 'https://example.com', description: 'Good' });
+      cy.get('#dynamicModalLinkHref').should(
+        'have.attr',
+        'href',
+        'https://example.com',
+      );
+    });
+
+    it('does not let one popup iframe handler outlive it', () => {
+      open({ url: 'https://a.test/', description: 'A', iframe: true });
+      cy.get('#dynamicModalLinkHref').should('have.class', 'iframe');
+
+      open({ url: 'https://b.test/', description: 'B' });
+
+      cy.get('#dynamicModalLinkHref').should('not.have.class', 'iframe');
+      cy.get('#dynamicModalLinkHref').should($anchor => {
+        expect($anchor[0].onclick, 'stale click handler').to.equal(null);
+      });
+    });
+  });
+});
+
+describe('Untrusted content reaching the iframe', () => {
+  const AFTER_THE_FADE = 3000;
+
+  it('refuses to open a script URL handed over by the modal', () => {
+    cy.visit('/');
+    cy.window().invoke('openDynamicPopup', {
+      name: 'Bad',
+      icon: { class: 'fa fa-test' },
+      url: 'javascript:window.__xss = true',
+      description: 'Watch',
+      iframe: true,
+    });
+
+    cy.get('#dynamicModalLinkHref').click({ force: true });
+
+    cy.wait(AFTER_THE_FADE);
+    cy.get('#main').find('iframe').should('not.exist');
+    cy.window().should('not.have.property', '__xss');
+  });
+
+  it('refuses a script URL supplied through the query string', () => {
+    cy.visit('/?iframe=javascript:window.__xss%20%3D%20true');
+
+    cy.wait(AFTER_THE_FADE);
+    cy.get('#main').find('iframe').should('not.exist');
+    cy.window().should('not.have.property', '__xss');
+  });
+
+  it('still opens an ordinary URL from the query string', () => {
+    cy.visit('/?iframe=https://example.com/');
+
+    cy.get('#main')
+      .find('iframe', { timeout: AFTER_THE_FADE })
+      .should('have.attr', 'src', 'https://example.com/');
+  });
+});

app/cypress/e2e/menu.spec.js

@@ -1,4 +1,70 @@
-// cypress/e2e/dynamic_popup.spec.js
+// cypress/e2e/menu.spec.js
+
+describe('Navigation dropdowns', () => {
+  beforeEach(() => {
+    cy.viewport(1280, 720);
+    cy.visit('/');
+  });
+
+  it('opens top-level dropdowns with explicit Bootstrap instances', () => {
+    cy.get('#navbarNavheader .nav-item.dropdown > .nav-link.dropdown-toggle')
+      .first()
+      .as('toggle')
+      .should('have.attr', 'data-bs-toggle', 'dropdown')
+      .and('have.attr', 'aria-expanded', 'false');
+
+    cy.get('@toggle').then($toggle => {
+      cy.window().then(win => {
+        expect(win.bootstrap.Dropdown.getInstance($toggle[0])).to.exist;
+      });
+    });
+
+    cy.get('@toggle')
+      .parent('.nav-item')
+      .find('> .dropdown-menu')
+      .as('menu')
+      .should('not.have.class', 'show')
+      .should('not.be.visible');
+
+    cy.get('@toggle').click();
+    cy.get('@toggle').should('have.attr', 'aria-expanded', 'true');
+    cy.get('@toggle').parent('.nav-item').should('have.class', 'dropdown');
+    cy.get('@menu')
+      .should('have.class', 'show')
+      .and('be.visible');
+  });
+
+  it('flips footer dropdowns upward where there is more space above', () => {
+    cy.get('#navbarNavfooter .nav-item .nav-link.dropdown-toggle')
+      .first()
+      .as('toggle');
+
+    cy.get('@toggle')
+      .parent('.nav-item')
+      .as('item')
+      .find('> .dropdown-menu')
+      .as('menu')
+      .should('not.have.class', 'show');
+
+    // Make sure the footer sits at the bottom of the viewport before clicking
+    // — otherwise the toggle could land near the top and chooseDirection would
+    // keep .dropdown (more space below than above).
+    // ensureScrollable:false because on short pages the body isn't scrollable
+    // and the footer is already in view (which is fine for this test).
+    cy.scrollTo('bottom', { ensureScrollable: false });
+    cy.get('@toggle').then($toggle => {
+      const rect = $toggle[0].getBoundingClientRect();
+      expect(rect.top, 'toggle is in the lower half of the viewport')
+        .to.be.greaterThan(Cypress.config('viewportHeight') / 2);
+    });
+    cy.get('@toggle').click({ scrollBehavior: false });
+    cy.get('@item').should('have.class', 'dropup');
+    cy.get('@item').should('not.have.class', 'dropdown');
+    cy.get('@menu')
+      .should('have.class', 'show')
+      .and('be.visible');
+  });
+});
 
 describe('Dynamic Popup', () => {
   const base = {

app/cypress/e2e/navbar_logo_visibility.spec.js

@@ -15,7 +15,7 @@ describe('Navbar Logo Visibility', () => {
 
   it('should become visible (opacity 1) after entering fullscreen', () => {
     cy.window().then(win => {
-      win.fullscreen();
+      win.enterFullscreen();
     });
     cy.get('#navbar_logo', { timeout: 4000 })
       .should('have.css', 'opacity', '1');
@@ -23,7 +23,7 @@ describe('Navbar Logo Visibility', () => {
 
   it('should become invisible again (opacity 0) after exiting fullscreen', () => {
     cy.window().then(win => {
-      win.fullscreen();
+      win.enterFullscreen();
       win.exitFullscreen();
     });
     cy.get('#navbar_logo', { timeout: 4000 })

app/eslint.config.js

@@ -0,0 +1,78 @@
+'use strict';
+/**
+ * Correctness only — eslint's recommended set, no stylistic rules.
+ *
+ * The browser scripts are plain <script> tags sharing one global scope: each
+ * file declares some functions and calls others declared elsewhere. That is why
+ * they are listed as globals and why no-redeclare is off — the declaring file
+ * would otherwise be reported for defining its own function.
+ */
+const js = require('@eslint/js');
+const globals = require('globals');
+
+// Vendored libraries plus the functions static/js files call across each other.
+// Keep this to names that really cross a file boundary. Every superfluous
+// entry is a permanent no-undef blind spot for a typo of that name.
+const SHARED = {
+  bootstrap: 'readonly',
+  marked: 'readonly',
+  $: 'readonly',
+  jQuery: 'readonly',
+  openDynamicPopup: 'readonly',
+  closeAllModals: 'readonly',
+  isSafeUrl: 'readonly',
+  openIframe: 'readonly',
+  enterFullscreen: 'readonly',
+  exitFullscreen: 'readonly',
+  setFullWidth: 'readonly',
+  initFullWidthFromUrl: 'readonly',
+  adjustScrollContainerHeight: 'readonly',
+  updateCustomScrollbar: 'readonly',
+};
+
+module.exports = [
+  { ignores: ['node_modules/**', 'static/vendor/**', 'cypress/screenshots/**'] },
+  {
+    files: ['static/js/**/*.js'],
+    languageOptions: {
+      ecmaVersion: 2022,
+      sourceType: 'script',
+      globals: { ...globals.browser, ...SHARED },
+    },
+    rules: {
+      ...js.configs.recommended.rules,
+      'no-redeclare': 'off',
+      // vars: 'local' — a top-level function here is the API other files and
+      // the templates call, so only unused locals are a defect.
+      'no-unused-vars': [
+        'error',
+        { vars: 'local', args: 'none', caughtErrors: 'none' },
+      ],
+    },
+  },
+  {
+    files: ['cypress/**/*.js'],
+    languageOptions: {
+      ecmaVersion: 2022,
+      sourceType: 'script',
+      globals: {
+        ...globals.browser,
+        ...globals.mocha,
+        cy: 'readonly',
+        Cypress: 'readonly',
+        expect: 'readonly',
+        assert: 'readonly',
+      },
+    },
+    rules: js.configs.recommended.rules,
+  },
+  {
+    files: ['scripts/**/*.js', 'cypress.config.js', 'eslint.config.js'],
+    languageOptions: {
+      ecmaVersion: 2022,
+      sourceType: 'commonjs',
+      globals: globals.node,
+    },
+    rules: js.configs.recommended.rules,
+  },
+];

app/i18n/ui/ar.yaml

@@ -0,0 +1,11 @@
+Alternatives: بدائل
+Close: إغلاق
+Copy: نسخ
+Identifier copied to clipboard!: تم نسخ المعرّف إلى الحافظة!
+Imprint: معلومات قانونية
+Information: معلومات
+Language: اللغة
+Open: فتح
+Open Link: فتح الرابط
+Options: خيارات
+Warning: تحذير

app/i18n/ui/bn.yaml

@@ -0,0 +1,11 @@
+Alternatives: অন্যান্য বিকল্প
+Close: বন্ধ করুন
+Copy: অনুলিপি
+Identifier copied to clipboard!: শনাক্তকারী ক্লিপবোর্ডে অনুলিপি করা হয়েছে!
+Imprint: আইনি তথ্য
+Information: তথ্য
+Language: ভাষা
+Open: খুলুন
+Open Link: লিঙ্ক খুলুন
+Options: বিকল্প
+Warning: সতর্কতা

app/i18n/ui/cs.yaml

@@ -0,0 +1,11 @@
+Alternatives: Alternativy
+Close: Zavřít
+Copy: Kopírovat
+Identifier copied to clipboard!: Identifikátor zkopírován do schránky!
+Imprint: Tiráž
+Information: Informace
+Language: Jazyk
+Open: Otevřít
+Open Link: Otevřít odkaz
+Options: Možnosti
+Warning: Upozornění

app/i18n/ui/da.yaml

@@ -0,0 +1,11 @@
+Alternatives: Alternativer
+Close: Luk
+Copy: Kopiér
+Identifier copied to clipboard!: Identifikator kopieret til udklipsholder!
+Imprint: Juridisk information
+Information: Information
+Language: Sprog
+Open: Åbn
+Open Link: Åbn link
+Options: Valgmuligheder
+Warning: Advarsel

app/i18n/ui/de.yaml

@@ -0,0 +1,11 @@
+Alternatives: Alternativen
+Close: Schließen
+Copy: Kopieren
+Identifier copied to clipboard!: Kennung in die Zwischenablage kopiert!
+Imprint: Impressum
+Information: Information
+Language: Sprache
+Open: Öffnen
+Open Link: Link öffnen
+Options: Optionen
+Warning: Warnung

app/i18n/ui/el.yaml

@@ -0,0 +1,11 @@
+Alternatives: Εναλλακτικές
+Close: Κλείσιμο
+Copy: Αντιγραφή
+Identifier copied to clipboard!: Το αναγνωριστικό αντιγράφηκε στο πρόχειρο!
+Imprint: Νομικές πληροφορίες
+Information: Πληροφορίες
+Language: Γλώσσα
+Open: Άνοιγμα
+Open Link: Άνοιγμα συνδέσμου
+Options: Επιλογές
+Warning: Προειδοποίηση

app/i18n/ui/es.yaml

@@ -0,0 +1,11 @@
+Alternatives: Alternativas
+Close: Cerrar
+Copy: Copiar
+Identifier copied to clipboard!: ¡Identificador copiado al portapapeles!
+Imprint: Aviso legal
+Information: Información
+Language: Idioma
+Open: Abrir
+Open Link: Abrir enlace
+Options: Opciones
+Warning: Advertencia

app/i18n/ui/fa.yaml

@@ -0,0 +1,11 @@
+Alternatives: جایگزین‌ها
+Close: بستن
+Copy: کپی
+Identifier copied to clipboard!: شناسه در کلیپ‌بورد کپی شد!
+Imprint: اطلاعات حقوقی
+Information: اطلاعات
+Language: زبان
+Open: باز کردن
+Open Link: باز کردن پیوند
+Options: گزینه‌ها
+Warning: هشدار

app/i18n/ui/fi.yaml

@@ -0,0 +1,11 @@
+Alternatives: Vaihtoehdot
+Close: Sulje
+Copy: Kopioi
+Identifier copied to clipboard!: Tunniste kopioitu leikepöydälle!
+Imprint: Oikeudelliset tiedot
+Information: Tiedot
+Language: Kieli
+Open: Avaa
+Open Link: Avaa linkki
+Options: Valinnat
+Warning: Varoitus

app/i18n/ui/fr.yaml

@@ -0,0 +1,11 @@
+Alternatives: Alternatives
+Close: Fermer
+Copy: Copier
+Identifier copied to clipboard!: Identifiant copié dans le presse-papiers !
+Imprint: Mentions légales
+Information: Informations
+Language: Langue
+Open: Ouvrir
+Open Link: Ouvrir le lien
+Options: Options
+Warning: Avertissement

app/i18n/ui/he.yaml

@@ -0,0 +1,11 @@
+Alternatives: חלופות
+Close: סגור
+Copy: העתק
+Identifier copied to clipboard!: המזהה הועתק ללוח!
+Imprint: מידע משפטי
+Information: מידע
+Language: שפה
+Open: פתח
+Open Link: פתח קישור
+Options: אפשרויות
+Warning: אזהרה

app/i18n/ui/hi.yaml

@@ -0,0 +1,11 @@
+Alternatives: अन्य विकल्प
+Close: बंद करें
+Copy: कॉपी करें
+Identifier copied to clipboard!: पहचानकर्ता क्लिपबोर्ड पर कॉपी हो गया!
+Imprint: कानूनी सूचना
+Information: जानकारी
+Language: भाषा
+Open: खोलें
+Open Link: लिंक खोलें
+Options: विकल्प
+Warning: चेतावनी

app/i18n/ui/hu.yaml

@@ -0,0 +1,11 @@
+Alternatives: Alternatívák
+Close: Bezárás
+Copy: Másolás
+Identifier copied to clipboard!: Az azonosító a vágólapra másolva!
+Imprint: Impresszum
+Information: Információ
+Language: Nyelv
+Open: Megnyitás
+Open Link: Hivatkozás megnyitása
+Options: Lehetőségek
+Warning: Figyelmeztetés

app/i18n/ui/id.yaml

@@ -0,0 +1,11 @@
+Alternatives: Alternatif
+Close: Tutup
+Copy: Salin
+Identifier copied to clipboard!: Pengenal disalin ke papan klip!
+Imprint: Informasi hukum
+Information: Informasi
+Language: Bahasa
+Open: Buka
+Open Link: Buka tautan
+Options: Opsi
+Warning: Peringatan

app/i18n/ui/it.yaml

@@ -0,0 +1,11 @@
+Alternatives: Alternative
+Close: Chiudi
+Copy: Copia
+Identifier copied to clipboard!: Identificatore copiato negli appunti!
+Imprint: Note legali
+Information: Informazioni
+Language: Lingua
+Open: Apri
+Open Link: Apri collegamento
+Options: Opzioni
+Warning: Avviso

app/i18n/ui/ja.yaml

@@ -0,0 +1,11 @@
+Alternatives: 代替
+Close: 閉じる
+Copy: コピー
+Identifier copied to clipboard!: 識別子をクリップボードにコピーしました！
+Imprint: 法的情報
+Information: 情報
+Language: 言語
+Open: 開く
+Open Link: リンクを開く
+Options: オプション
+Warning: 警告

app/i18n/ui/ko.yaml

@@ -0,0 +1,11 @@
+Alternatives: 대안
+Close: 닫기
+Copy: 복사
+Identifier copied to clipboard!: 식별자를 클립보드에 복사했습니다!
+Imprint: 법적 고지
+Information: 정보
+Language: 언어
+Open: 열기
+Open Link: 링크 열기
+Options: 옵션
+Warning: 경고

app/i18n/ui/nl.yaml

@@ -0,0 +1,11 @@
+Alternatives: Alternatieven
+Close: Sluiten
+Copy: Kopiëren
+Identifier copied to clipboard!: Identificatie gekopieerd naar klembord!
+Imprint: Colofon
+Information: Informatie
+Language: Taal
+Open: Openen
+Open Link: Link openen
+Options: Opties
+Warning: Waarschuwing

app/i18n/ui/pl.yaml

@@ -0,0 +1,11 @@
+Alternatives: Alternatywy
+Close: Zamknij
+Copy: Kopiuj
+Identifier copied to clipboard!: Identyfikator skopiowany do schowka!
+Imprint: Nota prawna
+Information: Informacja
+Language: Język
+Open: Otwórz
+Open Link: Otwórz link
+Options: Opcje
+Warning: Ostrzeżenie

app/i18n/ui/pt.yaml

@@ -0,0 +1,11 @@
+Alternatives: Alternativas
+Close: Fechar
+Copy: Copiar
+Identifier copied to clipboard!: Identificador copiado para a área de transferência!
+Imprint: Aviso legal
+Information: Informação
+Language: Idioma
+Open: Abrir
+Open Link: Abrir link
+Options: Opções
+Warning: Aviso

app/i18n/ui/ro.yaml

@@ -0,0 +1,11 @@
+Alternatives: Alternative
+Close: Închide
+Copy: Copiază
+Identifier copied to clipboard!: Identificator copiat în clipboard!
+Imprint: Notă legală
+Information: Informații
+Language: Limbă
+Open: Deschide
+Open Link: Deschide linkul
+Options: Opțiuni
+Warning: Avertisment

app/i18n/ui/ru.yaml

@@ -0,0 +1,11 @@
+Alternatives: Альтернативы
+Close: Закрыть
+Copy: Копировать
+Identifier copied to clipboard!: Идентификатор скопирован в буфер обмена!
+Imprint: Выходные данные
+Information: Информация
+Language: Язык
+Open: Открыть
+Open Link: Открыть ссылку
+Options: Варианты
+Warning: Предупреждение

app/i18n/ui/sv.yaml

@@ -0,0 +1,11 @@
+Alternatives: Alternativ
+Close: Stäng
+Copy: Kopiera
+Identifier copied to clipboard!: Identifierare kopierad till urklipp!
+Imprint: Juridisk information
+Information: Information
+Language: Språk
+Open: Öppna
+Open Link: Öppna länk
+Options: Val
+Warning: Varning

app/i18n/ui/th.yaml

@@ -0,0 +1,11 @@
+Alternatives: ทางเลือกอื่น
+Close: ปิด
+Copy: คัดลอก
+Identifier copied to clipboard!: คัดลอกตัวระบุไปยังคลิปบอร์ดแล้ว!
+Imprint: ข้อมูลทางกฎหมาย
+Information: ข้อมูล
+Language: ภาษา
+Open: เปิด
+Open Link: เปิดลิงก์
+Options: ตัวเลือก
+Warning: คำเตือน

app/i18n/ui/tr.yaml

@@ -0,0 +1,11 @@
+Alternatives: Alternatifler
+Close: Kapat
+Copy: Kopyala
+Identifier copied to clipboard!: Tanımlayıcı panoya kopyalandı!
+Imprint: Künye
+Information: Bilgi
+Language: Dil
+Open: Aç
+Open Link: Bağlantıyı aç
+Options: Seçenekler
+Warning: Uyarı

app/i18n/ui/uk.yaml

@@ -0,0 +1,11 @@
+Alternatives: Альтернативи
+Close: Закрити
+Copy: Копіювати
+Identifier copied to clipboard!: Ідентифікатор скопійовано в буфер обміну!
+Imprint: Вихідні дані
+Information: Інформація
+Language: Мова
+Open: Відкрити
+Open Link: Відкрити посилання
+Options: Варіанти
+Warning: Попередження

app/i18n/ui/ur.yaml

@@ -0,0 +1,11 @@
+Alternatives: متبادل
+Close: بند کریں
+Copy: نقل کریں
+Identifier copied to clipboard!: شناخت کنندہ کلپ بورڈ پر نقل ہو گیا!
+Imprint: قانونی معلومات
+Information: معلومات
+Language: زبان
+Open: کھولیں
+Open Link: لنک کھولیں
+Options: اختیارات
+Warning: انتباہ

app/i18n/ui/vi.yaml

@@ -0,0 +1,11 @@
+Alternatives: Lựa chọn thay thế
+Close: Đóng
+Copy: Sao chép
+Identifier copied to clipboard!: Đã sao chép mã định danh vào bộ nhớ tạm!
+Imprint: Thông tin pháp lý
+Information: Thông tin
+Language: Ngôn ngữ
+Open: Mở
+Open Link: Mở liên kết
+Options: Tùy chọn
+Warning: Cảnh báo

app/i18n/ui/zh.yaml

@@ -0,0 +1,11 @@
+Alternatives: 替代方案
+Close: 关闭
+Copy: 复制
+Identifier copied to clipboard!: 标识符已复制到剪贴板！
+Imprint: 法律声明
+Information: 信息
+Language: 语言
+Open: 打开
+Open Link: 打开链接
+Options: 选项
+Warning: 警告

app/package.json

@@ -1,5 +1,19 @@
 {
+  "dependencies": {
+    "@fortawesome/fontawesome-free": "^6.7.2",
+    "bootstrap": "5.2.2",
+    "bootstrap-icons": "1.9.1",
+    "jquery": "3.6.0",
+    "marked": "^4.3.0"
+  },
   "devDependencies": {
-    "cypress": "^14.5.1"
+    "@eslint/js": "^10.0.1",
+    "cypress": "^14.5.1",
+    "eslint": "^10.9.0",
+    "globals": "^17.11.0"
+  },
+  "scripts": {
+    "build": "node scripts/copy-vendor.js",
+    "postinstall": "node scripts/copy-vendor.js"
   }
 }

app/requirements.txt

@@ -1,3 +0,0 @@
-flask
-requests
-pyyaml

app/scripts/copy-vendor.js

@@ -0,0 +1,75 @@
+'use strict';
+/**
+ * Copies third-party browser assets from node_modules into static/vendor/
+ * so Flask can serve them without any CDN dependency.
+ * Runs automatically via the "postinstall" npm hook.
+ */
+const fs   = require('fs');
+const path = require('path');
+
+const NM     = path.join(__dirname, '..', 'node_modules');
+const VENDOR = path.join(__dirname, '..', 'static', 'vendor');
+
+function copyFile(src, dest) {
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+}
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    entry.isDirectory() ? copyDir(s, d) : fs.copyFileSync(s, d);
+  }
+}
+
+// Bootstrap CSS + JS bundle
+copyFile(
+  path.join(NM, 'bootstrap', 'dist', 'css', 'bootstrap.min.css'),
+  path.join(VENDOR, 'bootstrap', 'css', 'bootstrap.min.css')
+);
+copyFile(
+  path.join(NM, 'bootstrap', 'dist', 'css', 'bootstrap.rtl.min.css'),
+  path.join(VENDOR, 'bootstrap', 'css', 'bootstrap.rtl.min.css')
+);
+copyFile(
+  path.join(NM, 'bootstrap', 'dist', 'js', 'bootstrap.bundle.min.js'),
+  path.join(VENDOR, 'bootstrap', 'js', 'bootstrap.bundle.min.js')
+);
+
+// Bootstrap Icons CSS + embedded fonts
+copyFile(
+  path.join(NM, 'bootstrap-icons', 'font', 'bootstrap-icons.css'),
+  path.join(VENDOR, 'bootstrap-icons', 'font', 'bootstrap-icons.css')
+);
+copyDir(
+  path.join(NM, 'bootstrap-icons', 'font', 'fonts'),
+  path.join(VENDOR, 'bootstrap-icons', 'font', 'fonts')
+);
+
+// Font Awesome Free CSS + webfonts
+copyFile(
+  path.join(NM, '@fortawesome', 'fontawesome-free', 'css', 'all.min.css'),
+  path.join(VENDOR, 'fontawesome', 'css', 'all.min.css')
+);
+copyDir(
+  path.join(NM, '@fortawesome', 'fontawesome-free', 'webfonts'),
+  path.join(VENDOR, 'fontawesome', 'webfonts')
+);
+
+// marked – browser UMD build (path varies by version)
+const markedCandidates = [
+  path.join(NM, 'marked', 'marked.min.js'),              // v4.x
+  path.join(NM, 'marked', 'lib', 'marked.umd.min.js'),   // v5.x
+  path.join(NM, 'marked', 'dist', 'marked.min.js'),      // v9+
+];
+const markedSrc = markedCandidates.find(p => fs.existsSync(p));
+if (!markedSrc) throw new Error('marked: no browser UMD build found in node_modules');
+copyFile(markedSrc, path.join(VENDOR, 'marked', 'marked.min.js'));
+
+// jQuery
+copyFile(
+  path.join(NM, 'jquery', 'dist', 'jquery.min.js'),
+  path.join(VENDOR, 'jquery', 'jquery.min.js')
+);

app/static/css/default.css

@@ -111,6 +111,21 @@ div#navbarNavfooter li.nav-item {
   margin-right: 6px;
 }
 
+/* Prevent nav items from wrapping to a second line.
+   overflow is intentionally NOT set here — overflow-x:auto would
+   implicitly clip overflow-y too and hide dropdown menus that open
+   below the navbar. */
+div#navbarNavheader .navbar-nav,
+div#navbarNavfooter .navbar-nav {
+  flex-wrap: nowrap;
+}
+
+.dropdown-menu.language-menu {
+  max-height: 60vh;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+}
+
 main, footer, header, nav {
   position: relative;
   box-shadow: 
@@ -168,20 +183,22 @@ iframe{
 }
 
 #navbar_logo {
-  /* start invisible but in the layout (d-none will actually hide it) */
   opacity: 0;
-  transition: opacity var(--anim-duration) ease-in-out;
+  max-width: 0;
+  overflow: hidden;
+  transition: opacity var(--anim-duration) ease-in-out,
+              max-width var(--anim-duration) ease-in-out;
 }
 
 #navbar_logo.visible {
   opacity: 1 !important;
+  max-width: 300px;
 }
 
 
 /* 1. Make sure headers and footers can collapse */
 header,
 footer {
-  overflow: hidden;
   /* choose a max-height that’s >= your tallest header/footer */
   max-height: 200px;
   padding: 1rem;
@@ -190,9 +207,11 @@ footer {
     padding var(--anim-duration) ease-in-out;
 }
 
-/* 2. In fullscreen mode, collapse them */
+/* 2. In fullscreen mode, collapse them. overflow: hidden is scoped here
+   so dropdown menus can escape the header in normal mode. */
 body.fullscreen header,
 body.fullscreen footer {
+  overflow: hidden;
   max-height: 0;
   padding-top: 0;
   padding-bottom: 0;

app/static/css/navigation.css

@@ -1,9 +1,19 @@
-/* Top-level dropdown menu */
-.nav-item .dropdown-menu {
-    position: absolute; /* Important for positioning */
-    top: 100%; /* Default opening direction: downwards */
+/* Top-level dropdown menu — direction toggled by JS via .dropdown / .dropup */
+.nav-item.dropdown > .dropdown-menu,
+.nav-item.dropup > .dropdown-menu {
+    position: absolute;
     left: 0;
-    z-index: 1050; /* Ensures the menu appears above other elements */
+    z-index: 1050;
+}
+
+.nav-item.dropdown > .dropdown-menu {
+    top: 100%;
+    bottom: auto;
+}
+
+.nav-item.dropup > .dropdown-menu {
+    top: auto;
+    bottom: 100%;
 }
 
 /* Submenu position */

app/static/js/iframe.js

@@ -34,6 +34,10 @@ function syncIframeHeight() {
 
 // Function to open a URL in an iframe (jQuery version mit 1500 ms Fade)
 function openIframe(url) {
+    if (!isSafeUrl(url)) {
+        return;
+    }
+
     var $container    = scrollbarContainer    ? $(scrollbarContainer)    : null;
     var $customScroll = customScrollbar       ? $(customScrollbar)       : null;
     var $main         = $(mainElement);

app/static/js/modal.js

@@ -1,11 +1,48 @@
+function t(source) {
+  return (window.I18N || {})[source] || source;
+}
+
+const SAFE_URL_SCHEMES = ['http:', 'https:', 'mailto:'];
+
+function isSafeUrl(url) {
+  const probe = document.createElement('a');
+  probe.href = String(url == null ? '' : url);
+  return SAFE_URL_SCHEMES.includes(probe.protocol);
+}
+
+function iconAndName(item) {
+  const nodes = [];
+  if (item.icon && item.icon.class) {
+    const icon = document.createElement('i');
+    icon.className = item.icon.class;
+    nodes.push(icon, document.createTextNode(' '));
+  }
+  nodes.push(document.createTextNode(item.name == null ? '' : item.name));
+  return nodes;
+}
+
+function renderMarkdown(content) {
+  const escaped = String(content).replace(/</g, '&lt;').replace(/>/g, '&gt;');
+  const parsed = new DOMParser().parseFromString(marked.parse(escaped), 'text/html');
+
+  parsed.querySelectorAll('a[href]').forEach((anchor) => {
+    if (!SAFE_URL_SCHEMES.includes(anchor.protocol)) {
+      anchor.replaceWith(...anchor.childNodes);
+    }
+  });
+  parsed.querySelectorAll('img[src]').forEach((image) => {
+    if (!SAFE_URL_SCHEMES.includes(image.protocol)) {
+      image.replaceWith(image.alt || '');
+    }
+  });
+
+  return parsed.body.innerHTML;
+}
+
 function openDynamicPopup(subitem) {
   closeAllModals();
   const modalTitle = document.getElementById('dynamicModalLabel');
-  if (subitem.icon && subitem.icon.class) {
-    modalTitle.innerHTML = `<i class="${subitem.icon.class}"></i> ${subitem.name}`;
-  } else {
-    modalTitle.innerText = subitem.name;
-  }
+  modalTitle.replaceChildren(...iconAndName(subitem));
 
   const identifierBox = document.getElementById('dynamicIdentifierBox');
   const modalContent = document.getElementById('dynamicModalContent');
@@ -21,7 +58,7 @@ function openDynamicPopup(subitem) {
     const box = document.getElementById(boxId);
     if (content) {
       box.classList.remove('d-none');
-      document.getElementById(textId).innerHTML = marked.parse(content);
+      document.getElementById(textId).innerHTML = renderMarkdown(content);
     } else {
       box.classList.add('d-none');
     }
@@ -44,16 +81,19 @@ function openDynamicPopup(subitem) {
   if (subitem.url) {
     linkBox.classList.remove('d-none');
     linkHref.href = subitem.url;
-    linkHref.innerText = subitem.description || "Open Link";
+    if (!isSafeUrl(subitem.url)) {
+      linkHref.removeAttribute('href');
+    }
+    linkHref.innerText = subitem.description || t("Open Link");
+    linkHref.classList.remove('iframe');
+    linkHref.onclick = null;
     if (subitem.iframe) {
       linkHref.classList.add('iframe');
-      // Attach an event listener that prevents the default behavior and
-      // opens the URL in an iframe when clicked.
-      linkHref.addEventListener('click', function(event) {
+      linkHref.onclick = function(event) {
         event.preventDefault();
         openIframe(subitem.url);
-        closeAllModals()
-      });
+        closeAllModals();
+      };
     }
   } else {
     linkBox.classList.add('d-none');
@@ -69,13 +109,13 @@ function openDynamicPopup(subitem) {
       items.forEach(item => {
         const listItem = document.createElement('li');
         listItem.classList.add('list-group-item', 'd-flex', 'justify-content-between', 'align-items-center');
-        listItem.innerHTML = `
-          <span>
-            <i class="${item.icon.class}"></i> ${item.name}
-          </span>
-          <button class="btn btn-outline-secondary btn-sm">Open</button>
-        `;
-        listItem.querySelector('button').addEventListener('click', () => onClickHandler(item));
+        const label = document.createElement('span');
+        label.replaceChildren(...iconAndName(item));
+        const button = document.createElement('button');
+        button.className = 'btn btn-outline-secondary btn-sm';
+        button.textContent = t('Open');
+        listItem.replaceChildren(label, button);
+        button.addEventListener('click', () => onClickHandler(item));
         list.appendChild(listItem);
       });
     } else {
@@ -90,7 +130,7 @@ function openDynamicPopup(subitem) {
   copyButton.onclick = () => {
     modalContent.select();
     navigator.clipboard.writeText(modalContent.value).then(() => {
-      alert('Identifier copied to clipboard!');
+      alert(t('Identifier copied to clipboard!'));
     });
   };
 

app/static/js/navigation.js

@@ -1,6 +1,58 @@
 document.addEventListener('DOMContentLoaded', () => {
-  const menuItems = document.querySelectorAll('.nav-item.dropdown');
-  const subMenuItems = document.querySelectorAll('.dropdown-submenu');
+  function getDirectChildByClass(item, className) {
+    return Array.from(item.children).find(child => child.classList?.contains(className));
+  }
+
+  function getMenu(item) {
+    return getDirectChildByClass(item, 'dropdown-menu');
+  }
+
+  function getToggle(item) {
+    return getDirectChildByClass(item, 'dropdown-toggle');
+  }
+
+  function isTopLevelDropdown(item) {
+    return (
+      item.classList.contains('nav-item') &&
+      (item.classList.contains('dropdown') || item.classList.contains('dropup'))
+    );
+  }
+
+  function chooseDirection(item) {
+    const rect = item.getBoundingClientRect();
+    const spaceAbove = rect.top;
+    const spaceBelow = window.innerHeight - rect.bottom;
+    if (spaceAbove > spaceBelow) {
+      item.classList.add('dropup');
+      item.classList.remove('dropdown');
+    } else {
+      item.classList.add('dropdown');
+      item.classList.remove('dropup');
+    }
+  }
+
+  function ensureDropdownInstances(root = document) {
+    const scope = root && root.querySelectorAll ? root : document;
+    scope
+      .querySelectorAll('.nav-item.dropdown > .dropdown-toggle, .nav-item.dropup > .dropdown-toggle')
+      .forEach(toggle => {
+        toggle.setAttribute('data-bs-toggle', 'dropdown');
+        if (!toggle.hasAttribute('aria-expanded')) {
+          toggle.setAttribute('aria-expanded', 'false');
+        }
+        if (window.bootstrap?.Dropdown) {
+          // Use Popper strategy: 'fixed' so the menu is positioned relative
+          // to the viewport and escapes ancestors with overflow:hidden
+          // (e.g. <header> which clips for the fullscreen-collapse animation).
+          window.bootstrap.Dropdown.getInstance(toggle)?.dispose();
+          new window.bootstrap.Dropdown(toggle, {
+            popperConfig(defaultBsPopperConfig) {
+              return { ...defaultBsPopperConfig, strategy: 'fixed' };
+            },
+          });
+        }
+      });
+  }
 
   function addMenuEventListeners(items, isTopLevel) {
     items.forEach(item => {
@@ -8,7 +60,7 @@ document.addEventListener('DOMContentLoaded', () => {
 
       function onMouseEnter() {
         clearTimeout(timeout);
-        openMenu(item, isTopLevel);
+        openMenu(item, isTopLevel, 'hover');
       }
 
       function onMouseLeave() {
@@ -25,7 +77,29 @@ document.addEventListener('DOMContentLoaded', () => {
 
       // Open and adjust position on click
       item.addEventListener('click', (e) => {
+        const toggle = getToggle(item);
+        const clickedToggle = toggle && (e.target === toggle || toggle.contains(e.target));
+
+        if (isTopLevel && !clickedToggle) {
+          e.stopPropagation();
+          return;
+        }
+
         e.stopPropagation(); // Prevents menus from closing when clicking inside
+        if (isTopLevel) {
+          e.preventDefault();
+          if (window.bootstrap?.Dropdown) {
+            if (item.dataset.openedBy === 'click') {
+              closeMenu(item);
+            } else if (getMenu(item)) {
+              item.dataset.openedBy = 'click';
+              item.classList.add('open');
+              chooseDirection(item);
+              window.bootstrap.Dropdown.getOrCreateInstance(toggle).show();
+            }
+            return;
+          }
+        }
         if (item.classList.contains('open')) {
           closeMenu(item);
         } else {
@@ -35,39 +109,59 @@ document.addEventListener('DOMContentLoaded', () => {
     });
   }
 
+  const TOP_LEVEL_SELECTOR = '.nav-item.dropdown, .nav-item.dropup';
+
   function addAllMenuEventListeners() {
-    const updatedMenuItems = document.querySelectorAll('.nav-item.dropdown');
+    const updatedMenuItems = document.querySelectorAll(TOP_LEVEL_SELECTOR);
     const updatedSubMenuItems = document.querySelectorAll('.dropdown-submenu');
     addMenuEventListeners(updatedMenuItems, true);
     addMenuEventListeners(updatedSubMenuItems, false);
   }
 
+  ensureDropdownInstances();
   addAllMenuEventListeners();
 
   // Global click listener to close menus when clicking outside
   document.addEventListener('click', () => {
+    const menuItems = document.querySelectorAll(TOP_LEVEL_SELECTOR);
+    const subMenuItems = document.querySelectorAll('.dropdown-submenu');
     [...menuItems, ...subMenuItems].forEach(item => closeMenu(item));
   });
 
-  function openMenu(item, isTopLevel) {
+  function openMenu(item, isTopLevel, openedBy = 'script') {
     item.classList.add('open');
-    const submenu = item.querySelector('.dropdown-menu');
-    if (submenu) {
-      submenu.style.display = 'block';
-      submenu.style.opacity = '1';
-      submenu.style.visibility = 'visible';
-      adjustMenuPosition(submenu, item, isTopLevel);
+    const submenu = getMenu(item);
+    if (!submenu) return;
+    if (isTopLevel) {
+      item.dataset.openedBy = openedBy;
+      const toggle = getToggle(item);
+      if (toggle && window.bootstrap?.Dropdown) {
+        chooseDirection(item);
+        window.bootstrap.Dropdown.getOrCreateInstance(toggle).show();
+        return;
+      }
     }
+    submenu.style.display = 'block';
+    submenu.style.opacity = '1';
+    submenu.style.visibility = 'visible';
+    adjustMenuPosition(submenu, item, isTopLevel);
   }
 
   function closeMenu(item) {
     item.classList.remove('open');
-    const submenu = item.querySelector('.dropdown-menu');
-    if (submenu) {
-      submenu.style.display = 'none';
-      submenu.style.opacity = '0';
-      submenu.style.visibility = 'hidden';
+    delete item.dataset.openedBy;
+    const submenu = getMenu(item);
+    if (!submenu) return;
+    if (isTopLevelDropdown(item)) {
+      const toggle = getToggle(item);
+      if (toggle && window.bootstrap?.Dropdown) {
+        window.bootstrap.Dropdown.getOrCreateInstance(toggle).hide();
+        return;
+      }
     }
+    submenu.style.display = 'none';
+    submenu.style.opacity = '0';
+    submenu.style.visibility = 'hidden';
   }
 
   function isSmallScreen() {
@@ -75,7 +169,6 @@ document.addEventListener('DOMContentLoaded', () => {
   }
     
   function adjustMenuPosition(submenu, parent, isTopLevel) {
-    const rect = submenu.getBoundingClientRect();
     const parentRect = parent.getBoundingClientRect();
 
     const spaceAbove = parentRect.top;

app/templates/moduls/base.html.j2

@@ -1,30 +1,32 @@
 <!DOCTYPE html>
-<html lang="en">
+<html lang="{{ lang }}" dir="{{ lang_dir }}">
     <head>
         <title>{{platform.titel}}</title>
         <meta charset="utf-8" >
         <link
             rel="icon"
             type="image/x-icon"
-            href="{% if platform.favicon.cache %}{{ url_for('static', filename=platform.favicon.cache) }}{% endif %}"
+            href="{{ asset_src(platform.favicon) }}"
         >
+        <link rel="canonical" href="{{ url_for('localized_index', lang=lang, _external=True) }}">
+        {% for code in languages %}
+        <link rel="alternate" hreflang="{{ code }}" href="{{ url_for('localized_index', lang=code, _external=True) }}">
+        {% endfor %}
+        <link rel="alternate" hreflang="x-default" href="{{ url_for('index', _external=True) }}">
         <!-- Bootstrap CSS only -->
-        <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.2.2/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-Zenh87qX5JnK2Jl0vWa8Ck2rdkQ2Bzep5IDxbcnCeuOxjzrPF/et3URy9Bv1WTRi" crossorigin="anonymous">
+        <link href="{{ url_for('static', filename='vendor/bootstrap/css/bootstrap' ~ ('.rtl' if lang_dir == 'rtl' else '') ~ '.min.css') }}" rel="stylesheet">
         <!-- Bootstrap JavaScript Bundle with Popper -->
-        <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.2.2/dist/js/bootstrap.bundle.min.js" integrity="sha384-OERcA2EqjJCMA+/3y+gxIOqMEjwtxJY7qPCqsdltbNJuaOe923+mo//f6V8Qbsw3" crossorigin="anonymous"></script>
+        <script src="{{ url_for('static', filename='vendor/bootstrap/js/bootstrap.bundle.min.js') }}"></script>
         <!-- Bootstrap Icons -->
-        <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.9.1/font/bootstrap-icons.css">
+        <link rel="stylesheet" href="{{ url_for('static', filename='vendor/bootstrap-icons/font/bootstrap-icons.css') }}">
         <!-- Fontawesome -->
-        <script src="https://kit.fontawesome.com/56f96da298.js" crossorigin="anonymous"></script>
+        <link rel="stylesheet" href="{{ url_for('static', filename='vendor/fontawesome/css/all.min.css') }}">
         <!-- Markdown -->
-        <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
+        <script src="{{ url_for('static', filename='vendor/marked/marked.min.js') }}"></script>
         <link rel="stylesheet" href="{{ url_for('static', filename='css/default.css') }}">
         <link rel="stylesheet" href="{{ url_for('static', filename='css/custom_scrollbar.css') }}">
         <!-- JQuery -->
-        <script
-        src="https://code.jquery.com/jquery-3.6.0.min.js"
-        crossorigin="anonymous">
-        </script>
+        <script src="{{ url_for('static', filename='vendor/jquery/jquery.min.js') }}"></script>
     </head>
     <body
       {% if apod_bg %}
@@ -39,7 +41,7 @@
         <div class="container">
             <header class="header js-restore">
               <img
-                src="{{ url_for('static', filename=platform.logo.cache) }}"
+                src="{{ asset_src(platform.logo) }}"
                 alt="logo"
               />
               <h1>{{platform.titel}}</h1>
@@ -63,12 +65,13 @@
                     <p itemprop="name">{{ company.titel }} <br />
                     {{ company.subtitel }}</p>
                     <span><i class="fa-solid fa-location-dot"></i> {{ company.address.values() | join(", ") }}</span>
-                    <p><a href="{{company.imprint_url}}" class="iframe-link"><i class="fa-solid fa-scale-balanced"></i> Imprint</a></p>
+                    <p><a href="{{company.imprint_url}}" class="iframe-link"><i class="fa-solid fa-scale-balanced"></i> {{ t('Imprint') }}</a></p>
                 </div>
             </footer>
         </div>
         <!-- Include modal -->
         {% include "moduls/modal.html.j2" %}
+        <script>window.I18N = {{ ui_strings | tojson }};</script>
         {% for name in [
             'modal',
             'navigation',

app/templates/moduls/card.html.j2

@@ -4,9 +4,9 @@
       <div class="card-img-top">
         {% if card.icon.cache and card.icon.cache.endswith('.svg') %}
           {{ include_svg(card.icon.cache) }}
-        {% elif card.icon.cache %}
+        {% elif card.icon.cache or card.icon.external_url %}
           <img
-            src="{{ url_for('static', filename=card.icon.cache) }}"
+            src="{{ asset_src(card.icon) }}"
             alt="{{ card.title }}"
             style="width:100px; height:auto;"
             onerror="this.style.display='none'; this.nextElementSibling?.style.display='inline-block';">

app/templates/moduls/modal.html.j2

@@ -16,14 +16,14 @@
     <div class="modal-content">
       <div class="modal-header">
         <h5 class="modal-title" id="dynamicModalLabel"></h5>
-        <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
+        <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="{{ t('Close') }}"></button>
       </div>
       <div class="modal-body">
         <!-- Warning box with Markdown -->
-        {{ alert_box('dynamicModalWarning', 'alert-warning', 'fa-solid fa-triangle-exclamation', 'Warning', 'dynamicModalWarningText') }}
-        
+        {{ alert_box('dynamicModalWarning', 'alert-warning', 'fa-solid fa-triangle-exclamation', t('Warning'), 'dynamicModalWarningText') }}
+
         <!-- Info box with Markdown -->
-        {{ alert_box('dynamicModalInfo', 'alert-info', 'fa-solid fa-circle-info', 'Information', 'dynamicModalInfoText') }}
+        {{ alert_box('dynamicModalInfo', 'alert-info', 'fa-solid fa-circle-info', t('Information'), 'dynamicModalInfoText') }}
 
         <!-- Description text -->
         <div id="dynamicDescriptionText" class="mt-2 d-none"></div>
@@ -31,7 +31,7 @@
         <!-- Input box for Identifier -->
         <div id="dynamicIdentifierBox" class="input-group mt-2 d-none">
           <input type="text" id="dynamicModalContent" class="form-control" readonly>
-          <button class="btn btn-outline-secondary" type="button" id="dynamicCopyButton">Copy</button>
+          <button class="btn btn-outline-secondary" type="button" id="dynamicCopyButton">{{ t('Copy') }}</button>
         </div>
 
         <!-- Link -->
@@ -40,13 +40,13 @@
         </div>
 
         <!-- Options -->
-        {{ list_section('dynamicChildrenSection', 'Options', 'dynamicChildrenList') }}
+        {{ list_section('dynamicChildrenSection', t('Options'), 'dynamicChildrenList') }}
 
         <!-- Alternatives -->
-        {{ list_section('dynamicAlternativesSection', 'Alternatives', 'dynamicAlternativesList') }}
+        {{ list_section('dynamicAlternativesSection', t('Alternatives'), 'dynamicAlternativesList') }}
       </div>
       <div class="modal-footer">
-        <button type="button" class="btn btn-secondary" data-bs-dismiss="modal" onclick="closeAllModals()">Close</button>
+        <button type="button" class="btn btn-secondary" data-bs-dismiss="modal" onclick="closeAllModals()">{{ t('Close') }}</button>
       </div>
     </div>
   </div>

app/templates/moduls/navigation.html.j2

@@ -55,9 +55,9 @@
     <div class="collapse navbar-collapse" id="navbarNav{{menu_type}}">
         {% if menu_type == "header" %}
         <a class="navbar-brand align-items-center d-flex js-restore" id="navbar_logo" href="#">
-            <img 
-                src="{{ url_for('static', filename=platform.logo.cache) }}" 
-                alt="{{ platform.titel }}" 
+            <img
+                src="{{ asset_src(platform.logo) }}"
+                alt="{{ platform.titel }}"
                 class="d-inline-block align-text-top"
                 style="height:2rem">
             <div class="ms-2 d-flex flex-column">
@@ -85,7 +85,7 @@
                 {% else %}        
                 <!-- Dropdown Menu -->
                     <li class="nav-item dropdown">
-                        <a class="nav-link dropdown-toggle btn btn-light" id="navbarDropdown{{ loop.index }}" role="button" data-bs-display="dynamic" aria-expanded="false">
+                        <a class="nav-link dropdown-toggle btn btn-light" id="navbarDropdown{{ loop.index }}" role="button" data-bs-toggle="dropdown" data-bs-display="dynamic" aria-expanded="false">
                             {% if item.icon is defined and item.icon.class is defined %}
                                 {{ render_icon_and_name(item) }}
                             {% else %}
@@ -98,6 +98,23 @@
                     </li>
                 {% endif %}
             {% endfor %}
+            {% if menu_type == "header" %}
+            <li class="nav-item dropdown">
+                <a class="nav-link dropdown-toggle btn btn-light" id="navbarDropdownLanguage" role="button" data-bs-toggle="dropdown" data-bs-display="dynamic" aria-expanded="false" title="{{ t('Language') }}">
+                    <i class="fa-solid fa-language"></i> {{ languages[lang] }}
+                </a>
+                <ul class="dropdown-menu language-menu">
+                    {% for code, endonym in languages.items() %}
+                    <li>
+                        <a class="dropdown-item {% if code == lang %}active{% endif %}"
+                           href="{{ url_for('localized_index', lang=code) }}"
+                           hreflang="{{ code }}"
+                           lang="{{ code }}">{{ endonym }}</a>
+                    </li>
+                    {% endfor %}
+                </ul>
+            </li>
+            {% endif %}
         </ul>
     </div>
 </nav>

app/utils/__init__.py

@@ -0,0 +1 @@
+"""Utilities used by the Portfolio UI web application."""

app/utils/asset_resolver.py

@@ -0,0 +1,89 @@
+"""Split asset resolution into distinct fields so the template can
+render the right URL.
+
+Strategy
+--------
+
+1. **Probe** the source URL with a HEAD request. If it responds with an
+   ``image/*`` content type, embed it directly via ``external_url``
+   (no download necessary — the browser fetches it itself).
+2. **Cache** as a fallback: when the probe fails (404, non-image,
+   network error, …) try ``cache_manager.cache_file()`` to download
+   and serve via ``/static/cache/<file>``.
+3. **External fallback**: if the download fails too, still expose the
+   source URL via ``external_url`` so the browser shows at least the
+   alt-text or broken-image icon instead of an empty ``src``.
+
+Type safety
+-----------
+
+``cache`` only ever holds a relative path the static handler can serve;
+absolute URLs land in ``external_url`` and are rendered as-is. The
+previous fallback ``asset['cache'] = cached or asset['source']`` mixed
+both shapes — and the template's ``url_for('static', filename=...)``
+wrapper produced broken ``/static/https://…`` URLs when the source
+was an absolute URL the container couldn't fetch.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Optional
+
+import requests
+
+_PROBE_TIMEOUT_SECONDS = 3
+
+
+def _probe_image_url(url: str) -> bool:
+    """Return True if a HEAD request to ``url`` succeeds with an
+    ``image/*`` content type, suggesting the URL is safe to embed
+    directly as ``<img src>``."""
+    try:
+        resp = requests.head(url, allow_redirects=True, timeout=_PROBE_TIMEOUT_SECONDS)
+        resp.raise_for_status()
+    except requests.RequestException:
+        return False
+    content_type = resp.headers.get("Content-Type", "").lower()
+    return content_type.split(";", 1)[0].strip().startswith("image/")
+
+
+def resolve_asset_cache(
+    asset: dict,
+    cache_manager,
+    probe: Callable[[str], bool] = _probe_image_url,
+) -> None:
+    """Set ``asset['cache']`` (local, served via /static/) or
+    ``asset['external_url']`` (rendered as-is). Never both.
+
+    Tries the cheap direct-embed path first (``probe``) before falling
+    back to downloading via ``cache_manager``. See module docstring."""
+    source = asset.get("source")
+    asset["cache"] = None
+    asset["external_url"] = None
+    if not source:
+        return
+    if probe(source):
+        asset["external_url"] = source
+        return
+    cached = cache_manager.cache_file(source)
+    if cached:
+        asset["cache"] = cached
+    else:
+        asset["external_url"] = source
+
+
+def asset_src(asset: Optional[dict], url_for_static: Callable[[str], str]) -> str:
+    """Return the final URL for an asset dict prepared by
+    :func:`resolve_asset_cache`. ``url_for_static`` is a callable that
+    maps a relative cache path to its served URL (typically a partial
+    of Flask's ``url_for('static', filename=...)``)."""
+    if not asset:
+        return ""
+    external = asset.get("external_url")
+    if external:
+        return external
+    cached = asset.get("cache")
+    if cached:
+        return url_for_static(cached)
+    return ""

app/utils/cache_manager.py

@@ -1,7 +1,9 @@
-import os
 import hashlib
-import requests
 import mimetypes
+import os
+
+import requests
+
 
 class CacheManager:
     def __init__(self, cache_dir="static/cache"):
@@ -9,8 +11,7 @@ class CacheManager:
         self._ensure_cache_dir_exists()
 
     def _ensure_cache_dir_exists(self):
-        if not os.path.exists(self.cache_dir):
-            os.makedirs(self.cache_dir)
+        os.makedirs(self.cache_dir, exist_ok=True)
 
     def clear_cache(self):
         if os.path.exists(self.cache_dir):
@@ -20,8 +21,10 @@ class CacheManager:
                     os.remove(path)
 
     def cache_file(self, file_url):
-        # generate a short hash for filename
-        hash_suffix = hashlib.blake2s(file_url.encode('utf-8'), digest_size=8).hexdigest()
+        hash_suffix = hashlib.blake2s(
+            file_url.encode("utf-8"),
+            digest_size=8,
+        ).hexdigest()
         parts = file_url.rstrip("/").split("/")
         base = parts[-2] if parts[-1] == "download" else parts[-1]
 
@@ -31,7 +34,7 @@ class CacheManager:
         except requests.RequestException:
             return None
 
-        content_type = resp.headers.get('Content-Type', '')
+        content_type = resp.headers.get("Content-Type", "")
         ext = mimetypes.guess_extension(content_type.split(";")[0].strip()) or ".png"
         filename = f"{base}_{hash_suffix}{ext}"
         full_path = os.path.join(self.cache_dir, filename)
@@ -41,5 +44,4 @@ class CacheManager:
                 for chunk in resp.iter_content(1024):
                     f.write(chunk)
 
-        # return path relative to /static/
         return f"cache/{filename}"

app/utils/compute_card_classes.py

@@ -32,7 +32,7 @@ def compute_card_classes(cards):
                     lg_classes.append("col-lg-6")
                 else:
                     lg_classes.append("col-lg-4")
-    # md classes: If the number of cards is even or if not the last card, otherwise "col-md-12"
+    # Use a full-width last card on medium screens only when the total count is odd.
     md_classes = []
     for i in range(num_cards):
         if num_cards % 2 == 0 or i < num_cards - 1:

app/utils/configuration_resolver.py

@@ -1,4 +1,3 @@
-from pprint import pprint
 class ConfigurationResolver:
     """
     A class to resolve `link` entries in a nested configuration structure.
@@ -14,22 +13,9 @@ class ConfigurationResolver:
         """
         self._recursive_resolve(self.config, self.config)
 
-    def __load_children(self,path):
-        """
-        Check if explicitly children should be loaded and not parent
-        """
-        return path.split('.').pop() == "children"
-        
-    def _replace_in_dict_by_dict(self, dict_origine, old_key, new_dict):
-        if old_key in dict_origine:
-            # Entferne den alten Key
-            old_value = dict_origine.pop(old_key)
-            # Füge die neuen Key-Value-Paare hinzu
-            dict_origine.update(new_dict)
-
     def _replace_in_list_by_list(self, list_origine, old_element, new_elements):
         index = list_origine.index(old_element)
-        list_origine[index:index+1] = new_elements
+        list_origine[index : index + 1] = new_elements
 
     def _replace_element_in_list(self, list_origine, old_element, new_element):
         index = list_origine.index(old_element)
@@ -43,27 +29,43 @@ class ConfigurationResolver:
             for key, value in list(current_config.items()):
                 if key == "children":
                     if value is None or not isinstance(value, list):
-                        raise ValueError(f"Expected 'children' to be a list, but got {type(value).__name__} instead.")
+                        raise ValueError(
+                            "Expected 'children' to be a list, but got "
+                            f"{type(value).__name__} instead."
+                        )
                     for item in value:
                         if "link" in item:
-                            loaded_link = self._find_entry(root_config, self._mapped_key(item['link']), False)
+                            loaded_link = self._find_entry(
+                                root_config,
+                                self._mapped_key(item["link"]),
+                                False,
+                            )
                             if isinstance(loaded_link, list):
-                                self._replace_in_list_by_list(value,item,loaded_link)
+                                self._replace_in_list_by_list(value, item, loaded_link)
                             else:
-                                self._replace_element_in_list(value,item,loaded_link)  
+                                self._replace_element_in_list(value, item, loaded_link)
                         else:
-                            self._recursive_resolve(value, root_config)            
+                            self._recursive_resolve(value, root_config)
                 elif key == "link":
                     try:
-                        loaded = self._find_entry(root_config, self._mapped_key(value), False)
+                        loaded = self._find_entry(
+                            root_config, self._mapped_key(value), False
+                        )
                         if isinstance(loaded, list) and len(loaded) > 2:
-                            loaded = self._find_entry(root_config, self._mapped_key(value), False)  
+                            loaded = self._find_entry(
+                                root_config, self._mapped_key(value), False
+                            )
                         current_config.clear()
                         current_config.update(loaded)
-                    except Exception as e: 
+                    except Exception as e:
                         raise ValueError(
                             f"Error resolving link '{value}': {str(e)}. "
-                            f"Current part: {key}, Current config: {current_config}" + (f", Loaded: {loaded}" if 'loaded' in locals() or 'loaded' in globals() else "")
+                            f"Current part: {key}, Current config: {current_config}"
+                            + (
+                                f", Loaded: {loaded}"
+                                if "loaded" in locals() or "loaded" in globals()
+                                else ""
+                            )
                         )
                 else:
                     self._recursive_resolve(value, root_config)
@@ -71,69 +73,74 @@ class ConfigurationResolver:
             for item in current_config:
                 self._recursive_resolve(item, root_config)
 
-    def _get_children(self,current):
-        if isinstance(current, dict) and ("children" in current and current["children"]):
+    def _get_children(self, current):
+        if isinstance(current, dict) and (
+            "children" in current and current["children"]
+        ):
             current = current["children"]
         return current
 
-    def _mapped_key(self,name):
+    def _mapped_key(self, name):
         return name.replace(" ", "").lower()
-        
-    def _find_by_name(self,current, part):
+
+    def _find_by_name(self, current, part):
         return next(
-                    (item for item in current if isinstance(item, dict) and self._mapped_key(item.get("name", "")) == part),
-                    None
-                )
+            (
+                item
+                for item in current
+                if isinstance(item, dict)
+                and self._mapped_key(item.get("name", "")) == part
+            ),
+            None,
+        )
 
     def _find_entry(self, config, path, children):
         """
         Finds an entry in the configuration by a dot-separated path.
         Supports both dictionaries and lists with `children` navigation.
         """
-        parts = path.split('.')
+        parts = path.split(".")
         current = config
         for part in parts:
             if isinstance(current, list):
-                # If children explicit declared just load children
                 if part != "children":
-                    # Look for a matching name in the list
-                    found = self._find_by_name(current,part)
+                    found = self._find_by_name(current, part)
                     if found:
                         current = found
                         print(
-                            f"Matching entry for '{part}' in list. Path so far: {' > '.join(parts[:parts.index(part)+1])}. "
+                            f"Matching entry for '{part}' in list. Path so far: "
+                            f"{' > '.join(parts[: parts.index(part) + 1])}. "
                             f"Current list: {current}"
                         )
                     else:
                         raise ValueError(
-                            f"No matching entry for '{part}' in list. Path so far: {' > '.join(parts[:parts.index(part)+1])}. "
+                            f"No matching entry for '{part}' in list. Path so far: "
+                            f"{' > '.join(parts[: parts.index(part) + 1])}. "
                             f"Current list: {current}"
                         )
             elif isinstance(current, dict):
-                # Case-insensitive dictionary lookup
                 key = next((k for k in current if self._mapped_key(k) == part), None)
-                # If no fitting key was found search in the children
                 if key is None:
                     if "children" not in current:
                         raise KeyError(
-                        f"No 'children' found in current dictionary. Path so far: {' > '.join(parts[:parts.index(part)+1])}. "
-                        f"Current dictionary: {current}"
-                    )
-                    # The following line seems buggy; Why is children loaded allways and not just when children is set?
-                    current = self._find_by_name(current["children"],part)
-                    
-                    if not current:
-                        raise KeyError(
-                            f"Key '{part}' not found in dictionary. Path so far: {' > '.join(parts[:parts.index(part)+1])}. "
+                            "No 'children' found in current dictionary. Path so far: "
+                            f"{' > '.join(parts[: parts.index(part) + 1])}. "
                             f"Current dictionary: {current}"
                         )
-                else: 
+                    current = self._find_by_name(current["children"], part)
+
+                    if not current:
+                        raise KeyError(
+                            f"Key '{part}' not found in dictionary. Path so far: "
+                            f"{' > '.join(parts[: parts.index(part) + 1])}. "
+                            f"Current dictionary: {current}"
+                        )
+                else:
                     current = current[key]
-                
             else:
                 raise ValueError(
                     f"Invalid path segment '{part}'. Current type: {type(current)}. "
-                    f"Path so far: {' > '.join(parts[:parts.index(part)+1])}"
+                    f"Path so far: {' > '.join(parts[: parts.index(part) + 1])}"
                 )
             if children:
                 current = self._get_children(current)

app/utils/i18n.py

@@ -0,0 +1,134 @@
+"""Language negotiation and translation of the resolved configuration tree.
+
+Translation is catalogue-driven: a string is replaced only when the target
+language's catalogue holds an entry for the exact English source string.
+Anything unknown falls through to English, so a partially filled catalogue
+degrades instead of breaking.
+"""
+
+import logging
+from pathlib import Path
+
+import yaml
+
+try:
+    from app.utils.languages import LANGUAGES, RTL_LANGUAGES
+except ImportError:  # pragma: no cover - supports running from the app/ directory.
+    from utils.languages import LANGUAGES, RTL_LANGUAGES
+
+I18N_DIR = Path(__file__).resolve().parent.parent / "i18n"
+UI_DIR = I18N_DIR / "ui"
+CONTENT_DIR = I18N_DIR / "content"
+
+SOURCE_LANGUAGE = "en"
+
+
+AUTOFILL_KEYS = frozenset({"description", "text", "warning", "info", "subtitel"})
+
+TRANSLATABLE_KEYS = AUTOFILL_KEYS | frozenset({"name", "title"})
+
+UI_STRINGS = (
+    "Alternatives",
+    "Close",
+    "Copy",
+    "Identifier copied to clipboard!",
+    "Imprint",
+    "Information",
+    "Language",
+    "Open",
+    "Open Link",
+    "Options",
+    "Warning",
+)
+
+_catalogs: dict[str, dict[str, str]] = {}
+
+
+def direction(code):
+    """Return the writing direction of ``code`` as an HTML ``dir`` value."""
+    return "rtl" if code in RTL_LANGUAGES else "ltr"
+
+
+def read_catalog(path):
+    """Return the catalogue at ``path``, or an empty one if it is unusable.
+
+    Catalogues are hand-edited and machine-written, so a stray character must
+    degrade that language to English rather than take every page down with a
+    parse error. Non-string entries are dropped for the same reason: they would
+    otherwise reach the templates and render as ``42`` or ``null``.
+    """
+    if not path.exists():
+        return {}
+    try:
+        loaded = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, yaml.YAMLError):
+        logging.warning("Ignoring unreadable translation catalogue: %s", path)
+        return {}
+    if not isinstance(loaded, dict):
+        logging.warning(
+            "Ignoring translation catalogue that is not a mapping: %s", path
+        )
+        return {}
+    return {
+        key: value
+        for key, value in loaded.items()
+        if isinstance(key, str) and isinstance(value, str)
+    }
+
+
+def clear_catalogs():
+    """Drop the memoized catalogues so edited files are picked up."""
+    _catalogs.clear()
+
+
+def catalog(code):
+    """Return the merged UI and content catalogue for ``code``."""
+    if code not in _catalogs:
+        _catalogs[code] = {
+            **read_catalog(UI_DIR / f"{code}.yaml"),
+            **read_catalog(CONTENT_DIR / f"{code}.yaml"),
+        }
+    return _catalogs[code]
+
+
+def negotiate(accepted, default=SOURCE_LANGUAGE):
+    """Pick the best supported language from ``Accept-Language`` pairs.
+
+    Args:
+        accepted: iterable of ``(tag, quality)`` as produced by
+            ``flask.request.accept_languages``.
+        default: language returned when no tag is supported.
+
+    Werkzeug's own ``best_match`` returns an exact match before it considers
+    primary-tag fallbacks, so ``de-DE,en;q=0.8`` resolves to English. Matching
+    on the primary subtag up front avoids that.
+    """
+    best, best_quality = default, 0.0
+    for tag, quality in accepted:
+        code = tag.replace("_", "-").split("-")[0].lower()
+        if code in LANGUAGES and quality > best_quality:
+            best, best_quality = code, quality
+    return best
+
+
+def translate_tree(node, code, key=None):
+    """Return a copy of ``node`` with translatable leaves swapped for ``code``.
+
+    Args:
+        node: the resolved configuration tree, or any subtree of it.
+        code: target language code.
+        key: the mapping key ``node`` was reached through.
+    """
+    if isinstance(node, dict):
+        return {name: translate_tree(value, code, name) for name, value in node.items()}
+    if isinstance(node, list):
+        return [translate_tree(item, code, key) for item in node]
+    if isinstance(node, str) and key in TRANSLATABLE_KEYS:
+        return catalog(code).get(node, node)
+    return node
+
+
+def ui_strings(code):
+    """Return the interface strings for ``code``, keyed by their English source."""
+    entries = catalog(code)
+    return {source: entries.get(source, source) for source in UI_STRINGS}

app/utils/languages.py

@@ -0,0 +1,196 @@
+"""ISO 639-1 languages, their display names and writing direction.
+
+Generated by utils/generate_languages.py — edit that script, not this file.
+
+Display names are CLDR endonyms where CLDR covers the language and the English
+ISO 639-1 name for the 25 codes it does not.
+"""
+
+LANGUAGES = {
+    "en": "English",
+    "aa": "Qafar",
+    "ab": "Аԥсшәа",
+    "ae": "Avestan",
+    "af": "Afrikaans",
+    "ak": "Akan",
+    "am": "አማርኛ",
+    "an": "aragonés",
+    "ar": "العربية",
+    "as": "অসমীয়া",
+    "av": "Avaric",
+    "ay": "Aymara",
+    "az": "azərbaycan",
+    "ba": "башҡорт теле",
+    "be": "беларуская",
+    "bg": "български",
+    "bi": "Bislama",
+    "bm": "bamanakan",
+    "bn": "বাংলা",
+    "bo": "བོད་སྐད་",
+    "br": "brezhoneg",
+    "bs": "bosanski",
+    "ca": "català",
+    "ce": "нохчийн",
+    "ch": "Chamorro",
+    "co": "corsu",
+    "cr": "Cree",
+    "cs": "čeština",
+    "cu": "церковнослове́нскїй",
+    "cv": "чӑваш",
+    "cy": "Cymraeg",
+    "da": "dansk",
+    "de": "Deutsch",
+    "dv": "ދިވެހިބަސް",
+    "dz": "རྫོང་ཁ",
+    "ee": "eʋegbe",
+    "el": "Ελληνικά",
+    "eo": "Esperanto",
+    "es": "español",
+    "et": "eesti",
+    "eu": "euskara",
+    "fa": "فارسی",
+    "ff": "Pulaar",
+    "fi": "suomi",
+    "fj": "Fijian",
+    "fo": "føroyskt",
+    "fr": "français",
+    "fy": "Frysk",
+    "ga": "Gaeilge",
+    "gd": "Gàidhlig",
+    "gl": "galego",
+    "gn": "avañe’ẽ",
+    "gu": "ગુજરાતી",
+    "gv": "Gaelg",
+    "ha": "Hausa",
+    "he": "עברית",
+    "hi": "हिन्दी",
+    "ho": "Hiri Motu",
+    "hr": "hrvatski",
+    "ht": "Kreyòl Ayisyen",
+    "hu": "magyar",
+    "hy": "հայերեն",
+    "hz": "Herero",
+    "ia": "interlingua",
+    "id": "Indonesia",
+    "ie": "Interlingue",
+    "ig": "Igbo",
+    "ii": "ꆈꌠꉙ",
+    "ik": "Inupiaq",
+    "io": "Ido",
+    "is": "íslenska",
+    "it": "italiano",
+    "iu": "ᐃᓄᒃᑎᑐᑦ",
+    "ja": "日本語",
+    "jv": "Jawa",
+    "ka": "ქართული",
+    "kg": "Kongo",
+    "ki": "Gikuyu",
+    "kj": "Kuanyama",
+    "kk": "қазақ тілі",
+    "kl": "kalaallisut",
+    "km": "ខ្មែរ",
+    "kn": "ಕನ್ನಡ",
+    "ko": "한국어",
+    "kr": "Kanuri",
+    "ks": "کٲشُر",
+    "ku": "kurdî (kurmancî)",
+    "kv": "Komi",
+    "kw": "kernewek",
+    "ky": "кыргызча",
+    "la": "Latina",
+    "lb": "Lëtzebuergesch",
+    "lg": "Luganda",
+    "li": "Limburgan",
+    "ln": "lingála",
+    "lo": "ລາວ",
+    "lt": "lietuvių",
+    "lu": "Tshiluba",
+    "lv": "latviešu",
+    "mg": "Malagasy",
+    "mh": "Marshallese",
+    "mi": "Māori",
+    "mk": "македонски",
+    "ml": "മലയാളം",
+    "mn": "монгол",
+    "mr": "मराठी",
+    "ms": "Melayu",
+    "mt": "Malti",
+    "my": "မြန်မာ",
+    "na": "Nauru",
+    "nb": "norsk bokmål",
+    "nd": "isiNdebele",
+    "ne": "नेपाली",
+    "ng": "Ndonga",
+    "nl": "Nederlands",
+    "nn": "norsk nynorsk",
+    "no": "norsk",
+    "nr": "isiNdebele",
+    "nv": "Diné Bizaad",
+    "ny": "Nyanja",
+    "oc": "occitan",
+    "oj": "Ojibwa",
+    "om": "Oromoo",
+    "or": "ଓଡ଼ିଆ",
+    "os": "ирон",
+    "pa": "ਪੰਜਾਬੀ",
+    "pi": "Pali",
+    "pl": "polski",
+    "ps": "پښتو",
+    "pt": "português",
+    "qu": "Runasimi",
+    "rm": "rumantsch",
+    "rn": "Ikirundi",
+    "ro": "română",
+    "ru": "русский",
+    "rw": "Ikinyarwanda",
+    "sa": "संस्कृत भाषा",
+    "sc": "sardu",
+    "sd": "سنڌي",
+    "se": "davvisámegiella",
+    "sg": "Sängö",
+    "sh": "Serbo-Croatian",
+    "si": "සිංහල",
+    "sk": "slovenčina",
+    "sl": "slovenščina",
+    "sm": "Samoan",
+    "sn": "chiShona",
+    "so": "Soomaali",
+    "sq": "shqip",
+    "sr": "српски",
+    "ss": "siSwati",
+    "st": "Sesotho",
+    "su": "Basa Sunda",
+    "sv": "svenska",
+    "sw": "Kiswahili",
+    "ta": "தமிழ்",
+    "te": "తెలుగు",
+    "tg": "тоҷикӣ",
+    "th": "ไทย",
+    "ti": "ትግርኛ",
+    "tk": "türkmen dili",
+    "tl": "Tagalog",
+    "tn": "Setswana",
+    "to": "lea fakatonga",
+    "tr": "Türkçe",
+    "ts": "Xitsonga",
+    "tt": "татар",
+    "tw": "Twi",
+    "ty": "Tahitian",
+    "ug": "ئۇيغۇرچە",
+    "uk": "українська",
+    "ur": "اردو",
+    "uz": "o‘zbek",
+    "ve": "Tshivenḓa",
+    "vi": "Tiếng Việt",
+    "vo": "Volapük",
+    "wa": "walon",
+    "wo": "Wolof",
+    "xh": "IsiXhosa",
+    "yi": "ייִדיש",
+    "yo": "Èdè Yorùbá",
+    "za": "Vahcuengh",
+    "zh": "中文",
+    "zu": "isiZulu",
+}
+
+RTL_LANGUAGES = frozenset({"ar", "dv", "fa", "he", "ks", "ps", "sd", "ug", "ur", "yi"})

docker-compose.yml

@@ -1,15 +1,26 @@
-version: '3.8'
-
 services:
   portfolio:
+    # SPOT: IMAGE_NAME comes from .env (see env.example). No default —
+    # an empty tag would have compose fall back to `portfolio-portfolio`
+    # silently, which `make run-dev` would then fail to find.
+    image: ${IMAGE_NAME:?IMAGE_NAME must be set in .env (see env.example)}
     build:
       context: .
       dockerfile: Dockerfile
     container_name: portfolio
     ports:
-      - "${PORT:-5000}:${PORT:-5000}"
+      - "${PORT:?PORT must be set in .env (see env.example)}:${PORT:?PORT must be set in .env (see env.example)}"
     env_file:
       - .env
     volumes:
       - ./app:/app
+      - node_modules:/app/node_modules
+      - vendor:/app/static/vendor
+    # Run `npm install` on every container start so the named volumes
+    # reflect the current package.json (postinstall regenerates vendor/).
+    command: sh -c "npm install --prefix /app --no-audit --no-fund && python app.py"
     restart: unless-stopped
+
+volumes:
+  node_modules:
+  vendor:

env.example

@@ -1,2 +1,13 @@
 PORT=5001
-FLASK_ENV=production
+FLASK_ENV=production
+# Single source of truth for the Docker image tag — read by both the
+# Makefile (build/run-dev/run-prod) and docker-compose.yml so every
+# build path produces and consumes the same tag.
+IMAGE_NAME=portfolio
+# Comma-separated public hostnames. Leave empty and the app reflects whatever
+# Host header arrives into its canonical, hreflang and redirect URLs.
+TRUSTED_HOSTS=
+# LibreTranslate instance used by `make i18n` to fill app/i18n/content/.
+# Only needed when generating translations, never at runtime.
+LIBRETRANSLATE_URL=http://localhost:5002
+LIBRETRANSLATE_API_KEY=

main.py

@@ -3,11 +3,11 @@
 main.py - Proxy to Makefile targets for managing the Portfolio CMS Docker application.
 Automatically generates CLI commands based on the Makefile definitions.
 """
+
 import argparse
+import re
 import subprocess
 import sys
-import os
-import re
 from pathlib import Path
 
 MAKEFILE_PATH = Path(__file__).resolve().parent / "Makefile"
@@ -21,16 +21,17 @@ def load_targets(makefile_path):
     """
     targets = []
     pattern = re.compile(r"^([A-Za-z0-9_\-]+):")
-    with open(makefile_path, 'r') as f:
-        lines = f.readlines()
+    with open(makefile_path, "r", encoding="utf-8") as handle:
+        lines = handle.readlines()
     for idx, line in enumerate(lines):
         m = pattern.match(line)
         if m:
             name = m.group(1)
-            help_text = ''
-            # look for next non-empty line
-            if idx + 1 < len(lines) and lines[idx+1].lstrip().startswith('#'):
-                help_text = lines[idx+1].lstrip('# ').strip()
+            help_text = ""
+            if idx + 1 < len(lines):
+                next_line = lines[idx + 1].lstrip()
+                if next_line.startswith("#"):
+                    help_text = next_line.lstrip("# ").strip()
             targets.append((name, help_text))
     return targets
 
@@ -55,13 +56,13 @@ def main():
     parser.add_argument(
         "--dry-run",
         action="store_true",
-        help="Print the generated Make command without executing it."
+        help="Print the generated Make command without executing it.",
     )
 
     subparsers = parser.add_subparsers(
         title="Available commands",
         dest="command",
-        required=True
+        required=True,
     )
 
     targets = load_targets(MAKEFILE_PATH)
@@ -70,15 +71,9 @@ def main():
         sp.set_defaults(target=name)
 
     args = parser.parse_args()
-
-    if not args.command:
-        parser.print_help()
-        sys.exit(1)
-
     cmd = ["make", args.target]
     run_command(cmd, dry_run=args.dry_run)
 
 
 if __name__ == "__main__":
-    from pathlib import Path
-    main()
+    main()

pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "portfolio-ui"
+version = "2.0.0"
+description = "A lightweight YAML-driven portfolio and landing-page generator."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    # 3.1 introduced TRUSTED_HOSTS; an older Flask accepts the config key and
+    # ignores it, which would silently disable the host-forgery check.
+    "flask>=3.1",
+    "pyyaml",
+    "requests",
+]
+
+[project.optional-dependencies]
+dev = [
+    "babel",
+    "bandit",
+    "pip-audit",
+    "pycountry",
+    "ruff",
+    "yamllint",
+]
+
+[tool.setuptools]
+py-modules = ["main"]
+
+[tool.setuptools.packages.find]
+include = ["app", "app.*"]
+
+[tool.setuptools.package-data]
+app = [
+    "config.sample.yaml",
+    "i18n/ui/*.yaml",
+    "i18n/content/*.yaml",
+    "templates/**/*.j2",
+    "static/css/*.css",
+    "static/js/*.js",
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+extend-exclude = ["app/static/cache", "build"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]

requirements.txt

@@ -1 +0,0 @@
-python-dotenv

scripts/run-e2e.sh

@@ -0,0 +1,73 @@
+#!/bin/sh
+# Run the Cypress suite against a Flask app started by this script.
+#
+# Server and browser share one shell, so this works where act cannot reach the
+# host network. ELECTRON_RUN_AS_NODE is dropped before invoking Cypress because
+# VS Code exports it to child processes, which makes Cypress' bundled Electron
+# behave as Node and reject its own launch flags.
+#
+# Env:
+#   PORT     required, the port Flask binds and Cypress targets
+#   PYTHON   interpreter to run app.py with (default: python3)
+#   E2E_LOG  where Flask's output goes (default: /tmp/portfolio-e2e-flask.log)
+set -u
+
+PORT="${PORT:?PORT must be set (see env.example)}"
+PYTHON="${PYTHON:-python3}"
+E2E_LOG="${E2E_LOG:-/tmp/portfolio-e2e-flask.log}"
+FLASK_HOST=127.0.0.1
+export PORT FLASK_HOST
+
+APP_DIR="$(CDPATH='' cd -- "$(dirname -- "$0")/../app" && pwd)"
+BASE_URL="http://127.0.0.1:$PORT/"
+
+# cypress.config.js defaults to localhost, which resolves to ::1 first on a
+# dual-stack host — a different listener from the 127.0.0.1 one Flask binds and
+# this script probes. Pin all three to the same origin.
+export CYPRESS_baseUrl="$BASE_URL"
+
+# A foreign listener would be tested instead of the working tree. The predicate
+# is "something answers", deliberately without curl's -f: a foreign server that
+# is still returning 5xx right now would otherwise pass the guard and then be
+# picked up by the readiness probe once it recovers. --noproxy is what keeps
+# that same looser predicate from matching an HTTP proxy instead of the port.
+if curl -s --noproxy '*' --connect-timeout 2 --max-time 10 -o /dev/null "$BASE_URL"; then
+    echo "ERROR: something already serves port $PORT — Cypress would test that"
+    echo "       instead of your working tree. Stop it first ('make down' for"
+    echo "       the container, otherwise a stray 'python app.py')."
+    exit 1
+fi
+
+cd "$APP_DIR" || exit 1
+$PYTHON app.py > "$E2E_LOG" 2>&1 &
+flask_pid=$!
+trap 'kill "$flask_pid" 2>/dev/null || true' EXIT INT TERM
+
+echo "Waiting for $BASE_URL — follow with: tail -f $E2E_LOG"
+attempt=0
+while [ "$attempt" -lt 120 ]; do
+    # Liveness first: a server answering while ours is dead means we are about
+    # to hand Cypress somebody else's app.
+    if ! kill -0 "$flask_pid" 2>/dev/null; then
+        echo "ERROR: Flask exited during startup"
+        cat "$E2E_LOG"
+        exit 1
+    fi
+    if curl -sf --noproxy '*' --connect-timeout 2 --max-time 10 -o /dev/null "$BASE_URL"; then
+        break
+    fi
+    attempt=$((attempt + 1))
+    sleep 1
+done
+
+if ! curl -sf --noproxy '*' --connect-timeout 2 --max-time 10 -o /dev/null "$BASE_URL"; then
+    echo "ERROR: app never became ready"
+    cat "$E2E_LOG"
+    exit 1
+fi
+
+env -u ELECTRON_RUN_AS_NODE npx cypress run
+status=$?
+
+kill "$flask_pid" 2>/dev/null || true
+exit "$status"

tests/__init__.py

@@ -0,0 +1 @@
+

tests/integration/__init__.py

@@ -0,0 +1 @@
+

tests/integration/test_app_routes.py

@@ -0,0 +1,195 @@
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+
+app_module = None
+flask_app = None
+i18n = None
+_origin = None
+_workdir = None
+
+
+def setUpModule():
+    """Import the app with a disposable configuration as the working directory.
+
+    ``app.app`` reads ``config.yaml`` relative to the process working directory
+    at import time, so the chdir has to happen before the import.
+    """
+    global app_module, flask_app, i18n, _origin, _workdir
+
+    _origin = os.getcwd()
+    _workdir = tempfile.mkdtemp(prefix="portfolio-routes-")
+    shutil.copy(
+        REPO_ROOT / "app" / "config.sample.yaml", Path(_workdir) / "config.yaml"
+    )
+    os.chdir(_workdir)
+
+    from app import app as imported_module
+    from app.utils import i18n as imported_i18n
+
+    app_module = imported_module
+    flask_app = imported_module.app
+    i18n = imported_i18n
+    flask_app.config["NASA_API_KEY"] = None
+
+
+def tearDownModule():
+    os.chdir(_origin)
+    shutil.rmtree(_workdir, ignore_errors=True)
+
+
+class AppRouteMixin:
+    """Shared setup. A mixin rather than a TestCase subclass, so that every
+    test class below still names ``unittest.TestCase`` as a direct base — the
+    lint guardrail in tests/lint/ does not resolve inherited aliases."""
+
+    def setUp(self):
+        self.client = flask_app.test_client()
+        self.addCleanup(i18n.clear_catalogs)
+        self.addCleanup(flask_app.config["TRANSLATED_CONFIG"].clear)
+
+
+class TestRouting(AppRouteMixin, unittest.TestCase):
+    def test_unrelated_single_segment_paths_are_not_redirected(self):
+        for path in ("/robots.txt", "/favicon.ico", "/sitemap.xml"):
+            with self.subTest(path=path):
+                self.assertEqual(self.client.get(path).status_code, 404)
+
+    def test_language_path_redirects_to_the_canonical_trailing_slash(self):
+        response = self.client.get("/de")
+
+        self.assertEqual(response.status_code, 308)
+        self.assertTrue(response.headers["Location"].endswith("/de/"))
+
+    def test_supported_language_renders(self):
+        response = self.client.get("/de/")
+
+        self.assertEqual(response.status_code, 200)
+        self.assertIn('<html lang="de"', response.get_data(as_text=True))
+
+    def test_unsupported_language_is_not_found(self):
+        self.assertEqual(self.client.get("/xx/").status_code, 404)
+
+
+class TestNegotiation(AppRouteMixin, unittest.TestCase):
+    def test_regional_tag_beats_a_lower_ranked_exact_match(self):
+        response = self.client.get("/", headers={"Accept-Language": "de-DE,en;q=0.8"})
+
+        self.assertIn('<html lang="de"', response.get_data(as_text=True))
+
+    def test_negotiated_route_declares_that_it_varies(self):
+        response = self.client.get("/", headers={"Accept-Language": "de-DE"})
+
+        self.assertEqual(response.headers.get("Vary"), "Accept-Language")
+
+
+class TestEscaping(AppRouteMixin, unittest.TestCase):
+    def test_catalog_content_is_html_escaped(self):
+        i18n._catalogs["de"] = {"Imprint": "<script>alert(1)</script>"}
+
+        body = self.client.get("/de/").get_data(as_text=True)
+
+        self.assertNotIn("<script>alert(1)</script>", body)
+        self.assertIn("&lt;script&gt;alert(1)", body)
+
+
+class TestExternalUrls(AppRouteMixin, unittest.TestCase):
+    def test_forwarded_scheme_reaches_the_canonical_and_alternates(self):
+        body = self.client.get(
+            "/en/",
+            headers={"Host": "portfolio.example.org", "X-Forwarded-Proto": "https"},
+        ).get_data(as_text=True)
+
+        self.assertIn(
+            '<link rel="canonical" href="https://portfolio.example.org/en/">', body
+        )
+        self.assertIn('hreflang="ja" href="https://portfolio.example.org/ja/"', body)
+        self.assertNotIn("http://portfolio.example.org", body)
+
+    def test_trusted_hosts_are_parsed_from_a_comma_separated_list(self):
+        self.assertEqual(
+            app_module.trusted_hosts("a.test, b.test ,"), ["a.test", "b.test"]
+        )
+
+    def test_an_unset_trusted_hosts_value_disables_the_check(self):
+        self.assertIsNone(app_module.trusted_hosts(""))
+        self.assertIsNone(app_module.trusted_hosts("  ,  "))
+
+    def test_a_forged_host_is_rejected_once_trusted_hosts_are_named(self):
+        self.addCleanup(flask_app.config.__setitem__, "TRUSTED_HOSTS", None)
+        flask_app.config["TRUSTED_HOSTS"] = ["portfolio.example.org"]
+
+        forged = self.client.get("/de", headers={"Host": "evil.test"})
+        honest = self.client.get("/de/", headers={"Host": "portfolio.example.org"})
+
+        self.assertEqual(forged.status_code, 400)
+        self.assertEqual(honest.status_code, 200)
+
+    def test_forwarded_host_is_not_trusted(self):
+        response = self.client.get(
+            "/de",
+            headers={"Host": "portfolio.example.org", "X-Forwarded-Host": "evil.test"},
+        )
+
+        self.assertNotIn("evil.test", response.headers["Location"])
+
+        body = self.client.get(
+            "/en/",
+            headers={"Host": "portfolio.example.org", "X-Forwarded-Host": "evil.test"},
+        ).get_data(as_text=True)
+
+        self.assertNotIn("evil.test", body)
+
+
+class TestConfigurationReload(AppRouteMixin, unittest.TestCase):
+    def test_reloading_the_configuration_drops_the_catalog_memo(self):
+        i18n.catalog("de")
+        self.assertIn("de", i18n._catalogs)
+
+        app_module.load_config(flask_app)
+
+        self.assertEqual(i18n._catalogs, {})
+
+    def test_reloading_the_configuration_drops_the_translation_memo(self):
+        self.client.get("/de/")
+        self.assertIn("de", flask_app.config["TRANSLATED_CONFIG"])
+
+        app_module.load_config(flask_app)
+
+        self.assertEqual(flask_app.config["TRANSLATED_CONFIG"], {})
+
+
+class TestTrustedHostsWiring(unittest.TestCase):
+    def test_the_environment_reaches_the_flask_configuration(self):
+        script = (
+            "import json, sys;"
+            f"sys.path.insert(0, {str(REPO_ROOT)!r});"
+            "from app.app import app;"
+            "print('TRUSTED=' + json.dumps(app.config['TRUSTED_HOSTS']))"
+        )
+        result = subprocess.run(
+            [sys.executable, "-c", script],
+            cwd=_workdir,
+            env={**os.environ, "TRUSTED_HOSTS": "a.test, b.test"},
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+
+        reported = [
+            line for line in result.stdout.splitlines() if line.startswith("TRUSTED=")
+        ]
+        self.assertEqual(
+            json.loads(reported[-1][len("TRUSTED=") :]), ["a.test", "b.test"]
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/integration/test_asset_resolver_live.py

@@ -0,0 +1,84 @@
+"""Live network verification of the probe-first asset resolution path.
+
+The unit tests in ``tests/unit/test_asset_resolver.py`` cover every
+branch with mocks. This integration test exercises the real
+``https://file.infinito.nexus/assets/img/logo.png`` endpoint that
+``app/config.sample.yaml`` references for the Infinito.Nexus card. A
+green run proves the production resolver behaviour end-to-end:
+
+* probe (HEAD ``image/*``) succeeds against the canonical Infinito.Nexus
+  asset host, so ``external_url`` is populated directly and **no**
+  download is performed (the cache directory stays empty).
+
+The download-fallback branch (probe fails → ``cache_manager.cache_file``
+serves the asset locally) is intentionally not exercised against a live
+endpoint here — it is covered by mocked unit tests because every
+candidate "HEAD-fails, GET-succeeds" public URL we tried was flaky
+(Nextcloud's ``/download`` endpoint sporadically times out on HEAD even
+when GET works), which would make this guard test non-deterministic.
+"""
+
+from __future__ import annotations
+
+import os
+import unittest
+from tempfile import TemporaryDirectory
+from urllib.parse import urlparse
+
+import requests
+
+from app.utils.asset_resolver import resolve_asset_cache
+from app.utils.cache_manager import CacheManager
+
+INFINITO_LOGO_URL = "https://file.infinito.nexus/assets/img/logo.png"
+
+_SKIP_LIVE_NETWORK = os.environ.get("PORTFOLIO_SKIP_LIVE_NETWORK_TESTS") == "1"
+
+
+def _reachable(url: str) -> bool:
+    try:
+        return requests.head(url, allow_redirects=True, timeout=5).ok
+    except requests.RequestException:
+        return False
+
+
+@unittest.skipIf(
+    _SKIP_LIVE_NETWORK,
+    "PORTFOLIO_SKIP_LIVE_NETWORK_TESTS=1 — skipping live network tests",
+)
+class TestAssetResolverLive(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        if not _reachable(INFINITO_LOGO_URL):
+            raise unittest.SkipTest(
+                f"{urlparse(INFINITO_LOGO_URL).netloc} unreachable from this runner"
+            )
+
+    def test_infinito_nexus_logo_resolves_via_external_url_without_download(self):
+        with TemporaryDirectory() as tmp:
+            cache_dir = os.path.join(tmp, "cache")
+            cache_manager = CacheManager(cache_dir)
+            asset = {"source": INFINITO_LOGO_URL}
+
+            resolve_asset_cache(asset, cache_manager)
+
+            self.assertIsNone(
+                asset["cache"],
+                f"Expected probe-first path to skip download for {INFINITO_LOGO_URL}",
+            )
+            self.assertEqual(
+                asset["external_url"],
+                INFINITO_LOGO_URL,
+                "Probe-success URL must land in external_url so the template "
+                "embeds it directly instead of routing through /static/.",
+            )
+            self.assertEqual(
+                os.listdir(cache_dir),
+                [],
+                "Cache directory must stay empty when probe succeeds — "
+                "downloading would waste bandwidth.",
+            )
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/integration/test_python_packaging.py

@@ -0,0 +1,72 @@
+import re
+import tomllib
+import unittest
+from pathlib import Path
+
+
+def distributions(requirements):
+    """Return the distribution names of PEP 508 requirement strings."""
+    return {
+        re.split(r"[<>=!~\[; ]", requirement, maxsplit=1)[0]
+        for requirement in requirements
+    }
+
+
+class TestPythonPackaging(unittest.TestCase):
+    def setUp(self) -> None:
+        self.repo_root = Path(__file__).resolve().parents[2]
+        self.pyproject_path = self.repo_root / "pyproject.toml"
+
+        with self.pyproject_path.open("rb") as handle:
+            self.pyproject = tomllib.load(handle)
+
+    def test_pyproject_defines_build_system_and_runtime_dependencies(self):
+        build_system = self.pyproject["build-system"]
+        project = self.pyproject["project"]
+
+        self.assertEqual(build_system["build-backend"], "setuptools.build_meta")
+        self.assertIn("setuptools>=69", build_system["requires"])
+        self.assertGreaterEqual(
+            distributions(project["dependencies"]),
+            {"flask", "pyyaml", "requests"},
+        )
+        self.assertEqual(project["requires-python"], ">=3.12")
+
+    def test_flask_is_pinned_to_a_version_that_honours_trusted_hosts(self):
+        requirement = next(
+            item
+            for item in self.pyproject["project"]["dependencies"]
+            if item.startswith("flask")
+        )
+
+        self.assertIn(">=3.1", requirement)
+
+    def test_pyproject_defines_dev_dependencies_and_package_contents(self):
+        project = self.pyproject["project"]
+        setuptools_config = self.pyproject["tool"]["setuptools"]
+        package_find = setuptools_config["packages"]["find"]
+        package_data = setuptools_config["package-data"]["app"]
+
+        self.assertGreaterEqual(
+            distributions(project["optional-dependencies"]["dev"]),
+            {"bandit", "pip-audit", "ruff", "yamllint"},
+        )
+        self.assertEqual(setuptools_config["py-modules"], ["main"])
+        self.assertEqual(package_find["include"], ["app", "app.*"])
+        self.assertIn("config.sample.yaml", package_data)
+        self.assertIn("templates/**/*.j2", package_data)
+        self.assertIn("static/css/*.css", package_data)
+        self.assertIn("static/js/*.js", package_data)
+
+    def test_legacy_requirements_files_are_removed(self):
+        self.assertFalse((self.repo_root / "requirements.txt").exists())
+        self.assertFalse((self.repo_root / "requirements-dev.txt").exists())
+        self.assertFalse((self.repo_root / "app" / "requirements.txt").exists())
+
+    def test_package_init_files_exist(self):
+        self.assertTrue((self.repo_root / "app" / "__init__.py").is_file())
+        self.assertTrue((self.repo_root / "app" / "utils" / "__init__.py").is_file())
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/integration/test_yaml_syntax.py

@@ -0,0 +1,43 @@
+import unittest
+from pathlib import Path
+
+import yaml
+
+SKIP_DIR_NAMES = {".git", ".ruff_cache", "__pycache__", "node_modules"}
+SKIP_FILES = {"app/config.yaml"}
+YAML_SUFFIXES = {".yml", ".yaml"}
+
+
+class TestYamlSyntax(unittest.TestCase):
+    def test_all_repository_yaml_files_are_valid(self):
+        repo_root = Path(__file__).resolve().parents[2]
+        invalid_files = []
+
+        for path in repo_root.rglob("*"):
+            if not path.is_file() or path.suffix not in YAML_SUFFIXES:
+                continue
+
+            relative_path = path.relative_to(repo_root).as_posix()
+            if relative_path in SKIP_FILES:
+                continue
+
+            if any(part in SKIP_DIR_NAMES for part in path.parts):
+                continue
+
+            try:
+                with path.open("r", encoding="utf-8") as handle:
+                    yaml.safe_load(handle)
+            except yaml.YAMLError as error:
+                invalid_files.append((relative_path, str(error).splitlines()[0]))
+            except Exception as error:
+                invalid_files.append((relative_path, f"Unexpected error: {error}"))
+
+        self.assertFalse(
+            invalid_files,
+            "Found invalid YAML files:\n"
+            + "\n".join(f"- {path}: {error}" for path, error in invalid_files),
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/lint/__init__.py

@@ -0,0 +1 @@
+

tests/lint/test_all_test_files_have_tests.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+import ast
+import unittest
+from pathlib import Path
+
+
+class TestTestFilesContainUnittestTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.repo_root = Path(__file__).resolve().parents[2]
+        self.tests_dir = self.repo_root / "tests"
+        self.assertTrue(
+            self.tests_dir.is_dir(),
+            f"'tests' directory not found at: {self.tests_dir}",
+        )
+
+    def _iter_test_files(self) -> list[Path]:
+        return sorted(self.tests_dir.rglob("test_*.py"))
+
+    def _file_contains_runnable_unittest_test(self, path: Path) -> bool:
+        source = path.read_text(encoding="utf-8")
+
+        try:
+            tree = ast.parse(source, filename=str(path))
+        except SyntaxError as error:
+            raise AssertionError(f"SyntaxError in {path}: {error}") from error
+
+        testcase_aliases = {"TestCase"}
+        unittest_aliases = {"unittest"}
+
+        for node in tree.body:
+            if isinstance(node, ast.Import):
+                for import_name in node.names:
+                    if import_name.name == "unittest":
+                        unittest_aliases.add(import_name.asname or "unittest")
+            elif isinstance(node, ast.ImportFrom) and node.module == "unittest":
+                for import_name in node.names:
+                    if import_name.name == "TestCase":
+                        testcase_aliases.add(import_name.asname or "TestCase")
+
+        def is_testcase_base(base: ast.expr) -> bool:
+            if isinstance(base, ast.Name) and base.id in testcase_aliases:
+                return True
+
+            if isinstance(base, ast.Attribute) and base.attr == "TestCase":
+                return (
+                    isinstance(base.value, ast.Name)
+                    and base.value.id in unittest_aliases
+                )
+
+            return False
+
+        for node in tree.body:
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and (
+                node.name.startswith("test_")
+            ):
+                return True
+
+        for node in tree.body:
+            if not isinstance(node, ast.ClassDef):
+                continue
+
+            if not any(is_testcase_base(base) for base in node.bases):
+                continue
+
+            for item in node.body:
+                if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)) and (
+                    item.name.startswith("test_")
+                ):
+                    return True
+
+        return False
+
+    def test_all_test_py_files_contain_runnable_tests(self) -> None:
+        test_files = self._iter_test_files()
+        self.assertTrue(test_files, "No test_*.py files found under tests/")
+
+        offenders = []
+        for path in test_files:
+            if not self._file_contains_runnable_unittest_test(path):
+                offenders.append(path.relative_to(self.repo_root).as_posix())
+
+        self.assertFalse(
+            offenders,
+            "These test_*.py files do not define any unittest-runnable tests:\n"
+            + "\n".join(f"- {path}" for path in offenders),
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/lint/test_test_file_naming.py

@@ -0,0 +1,25 @@
+import unittest
+from pathlib import Path
+
+
+class TestTestFileNaming(unittest.TestCase):
+    def test_all_python_files_use_test_prefix(self):
+        tests_root = Path(__file__).resolve().parents[1]
+        invalid_files = []
+
+        for path in tests_root.rglob("*.py"):
+            if path.name == "__init__.py":
+                continue
+
+            if not path.name.startswith("test_"):
+                invalid_files.append(path.relative_to(tests_root).as_posix())
+
+        self.assertFalse(
+            invalid_files,
+            "The following Python files do not start with 'test_':\n"
+            + "\n".join(f"- {path}" for path in invalid_files),
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/lint/test_tooling_configuration.py

@@ -0,0 +1,78 @@
+"""Guards for configuration that no other test observes.
+
+Each assertion here stands for a defect that was found by deleting the line it
+checks: the deletion is invisible to every suite, and its effect only shows up
+in production or in a fresh checkout.
+"""
+
+import re
+import tomllib
+import unittest
+from pathlib import Path
+
+import yaml
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+
+
+class TestYamllintConfiguration(unittest.TestCase):
+    def setUp(self):
+        self.config = yaml.safe_load(
+            (REPO_ROOT / ".yamllint").read_text(encoding="utf-8")
+        )
+
+    def test_duplicate_keys_are_an_error(self):
+        self.assertEqual(self.config["rules"]["key-duplicates"], "enable")
+
+    def test_the_directories_that_collect_foreign_yaml_are_ignored(self):
+        ignored = self.config["ignore"].split()
+
+        self.assertGreaterEqual(
+            set(ignored),
+            {".git/", ".venv/", "node_modules/", "app/node_modules/"},
+        )
+
+
+class TestRunTargets(unittest.TestCase):
+    def setUp(self):
+        self.makefile = (REPO_ROOT / "Makefile").read_text(encoding="utf-8")
+        self.recipes = {
+            name: body
+            for name, body in re.findall(
+                r"^(run-dev|run-prod):[^\n]*\n((?:\t[^\n]*\n)+)",
+                self.makefile,
+                re.MULTILINE,
+            )
+        }
+
+    def test_both_run_targets_exist(self):
+        self.assertEqual(set(self.recipes), {"run-dev", "run-prod"})
+
+    def test_the_container_is_told_which_hosts_are_trusted(self):
+        for name, body in self.recipes.items():
+            with self.subTest(target=name):
+                self.assertIn("TRUSTED_HOSTS", body)
+
+    def test_the_container_is_told_which_port_to_bind(self):
+        for name, body in self.recipes.items():
+            with self.subTest(target=name):
+                self.assertIn('-e PORT="$$PORT"', body)
+
+    def test_the_whole_env_file_is_not_handed_to_the_web_container(self):
+        for name, body in self.recipes.items():
+            with self.subTest(target=name):
+                self.assertNotIn("--env-file", body)
+
+
+class TestPackagedCatalogs(unittest.TestCase):
+    def test_the_interface_catalogs_are_declared_as_package_data(self):
+        with (REPO_ROOT / "pyproject.toml").open("rb") as handle:
+            pyproject = tomllib.load(handle)
+
+        package_data = pyproject["tool"]["setuptools"]["package-data"]["app"]
+
+        self.assertIn("i18n/ui/*.yaml", package_data)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/security/__init__.py

@@ -0,0 +1 @@
+

tests/security/test_config_hygiene.py

@@ -0,0 +1,57 @@
+import subprocess
+import unittest
+from pathlib import Path
+
+import yaml
+
+
+class TestConfigHygiene(unittest.TestCase):
+    def setUp(self) -> None:
+        self.repo_root = Path(__file__).resolve().parents[2]
+        self.sample_config_path = self.repo_root / "app" / "config.sample.yaml"
+
+    def _is_tracked(self, path: str) -> bool:
+        result = subprocess.run(
+            ["git", "ls-files", "--error-unmatch", path],
+            cwd=self.repo_root,
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+        return result.returncode == 0
+
+    def _find_values_for_key(self, data, key_name: str):
+        if isinstance(data, dict):
+            for key, value in data.items():
+                if key == key_name:
+                    yield value
+                yield from self._find_values_for_key(value, key_name)
+        elif isinstance(data, list):
+            for item in data:
+                yield from self._find_values_for_key(item, key_name)
+
+    def test_runtime_only_files_are_ignored_and_untracked(self):
+        gitignore_lines = (
+            (self.repo_root / ".gitignore").read_text(encoding="utf-8").splitlines()
+        )
+
+        self.assertIn("app/config.yaml", gitignore_lines)
+        self.assertIn(".env", gitignore_lines)
+        self.assertFalse(self._is_tracked("app/config.yaml"))
+        self.assertFalse(self._is_tracked(".env"))
+
+    def test_sample_config_keeps_the_nasa_api_key_placeholder(self):
+        with self.sample_config_path.open("r", encoding="utf-8") as handle:
+            sample_config = yaml.safe_load(handle)
+
+        nasa_api_keys = list(self._find_values_for_key(sample_config, "nasa_api_key"))
+        self.assertEqual(
+            nasa_api_keys,
+            ["YOUR_REAL_KEY_HERE"],
+            "config.sample.yaml should only contain the documented NASA API key "
+            "placeholder.",
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/security/test_sample_config_urls.py

@@ -0,0 +1,43 @@
+import unittest
+from pathlib import Path
+
+import yaml
+
+ALLOWED_URL_PREFIXES = ("https://", "mailto:", "tel:")
+URL_KEYS = {"url", "imprint", "imprint_url"}
+
+
+class TestSampleConfigUrls(unittest.TestCase):
+    def setUp(self) -> None:
+        repo_root = Path(__file__).resolve().parents[2]
+        sample_config_path = repo_root / "app" / "config.sample.yaml"
+        with sample_config_path.open("r", encoding="utf-8") as handle:
+            self.sample_config = yaml.safe_load(handle)
+
+    def _iter_urls(self, data, path="root"):
+        if isinstance(data, dict):
+            for key, value in data.items():
+                next_path = f"{path}.{key}"
+                if key in URL_KEYS and isinstance(value, str):
+                    yield next_path, value
+                yield from self._iter_urls(value, next_path)
+        elif isinstance(data, list):
+            for index, item in enumerate(data):
+                yield from self._iter_urls(item, f"{path}[{index}]")
+
+    def test_sample_config_urls_use_safe_schemes(self):
+        invalid_urls = [
+            f"{path} -> {url}"
+            for path, url in self._iter_urls(self.sample_config)
+            if not url.startswith(ALLOWED_URL_PREFIXES)
+        ]
+
+        self.assertFalse(
+            invalid_urls,
+            "The sample config contains URLs with unsupported schemes:\n"
+            + "\n".join(f"- {entry}" for entry in invalid_urls),
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/__init__.py

@@ -0,0 +1 @@
+"""Unit test package for Portfolio UI."""

tests/unit/test_asset_resolver.py

@@ -0,0 +1,188 @@
+import unittest
+from unittest.mock import Mock, patch
+
+import requests
+
+from app.utils.asset_resolver import (
+    _probe_image_url,
+    asset_src,
+    resolve_asset_cache,
+)
+
+
+def _url_for_static(filename):
+    return f"/static/{filename}"
+
+
+def _always_probes_false(_url):
+    return False
+
+
+def _always_probes_true(_url):
+    return True
+
+
+class TestResolveAssetCache(unittest.TestCase):
+    def test_probe_success_skips_cache_and_embeds_directly(self):
+        cache_manager = Mock()
+        asset = {"source": "https://example.test/logo.png"}
+
+        resolve_asset_cache(asset, cache_manager, probe=_always_probes_true)
+
+        self.assertIsNone(asset["cache"])
+        self.assertEqual(asset["external_url"], "https://example.test/logo.png")
+        cache_manager.cache_file.assert_not_called()
+
+    def test_local_cache_path_assigned_when_probe_fails_but_download_succeeds(self):
+        cache_manager = Mock()
+        cache_manager.cache_file.return_value = "cache/logo_abc.png"
+        asset = {"source": "https://example.test/logo.png"}
+
+        resolve_asset_cache(asset, cache_manager, probe=_always_probes_false)
+
+        self.assertEqual(asset["cache"], "cache/logo_abc.png")
+        self.assertIsNone(asset["external_url"])
+        cache_manager.cache_file.assert_called_once_with(
+            "https://example.test/logo.png"
+        )
+
+    def test_external_url_fallback_when_probe_and_download_both_fail(self):
+        cache_manager = Mock()
+        cache_manager.cache_file.return_value = None
+        asset = {"source": "https://file.infinito.nexus/assets/img/logo.png"}
+
+        resolve_asset_cache(asset, cache_manager, probe=_always_probes_false)
+
+        self.assertIsNone(asset["cache"])
+        self.assertEqual(
+            asset["external_url"],
+            "https://file.infinito.nexus/assets/img/logo.png",
+        )
+
+    def test_missing_source_leaves_both_fields_none(self):
+        cache_manager = Mock()
+        probe = Mock()
+        asset = {"class": "fa-solid fa-link"}
+
+        resolve_asset_cache(asset, cache_manager, probe=probe)
+
+        self.assertIsNone(asset["cache"])
+        self.assertIsNone(asset["external_url"])
+        cache_manager.cache_file.assert_not_called()
+        probe.assert_not_called()
+
+    def test_empty_source_treated_as_missing(self):
+        cache_manager = Mock()
+        probe = Mock()
+        asset = {"source": ""}
+
+        resolve_asset_cache(asset, cache_manager, probe=probe)
+
+        self.assertIsNone(asset["cache"])
+        self.assertIsNone(asset["external_url"])
+        cache_manager.cache_file.assert_not_called()
+        probe.assert_not_called()
+
+
+class TestProbeImageUrl(unittest.TestCase):
+    def _response(self, content_type, raise_exc=None):
+        resp = Mock()
+        if raise_exc:
+            resp.raise_for_status.side_effect = raise_exc
+        else:
+            resp.raise_for_status.return_value = None
+        resp.headers = {"Content-Type": content_type}
+        return resp
+
+    @patch("app.utils.asset_resolver.requests.head")
+    def test_returns_true_for_image_content_type(self, mock_head):
+        mock_head.return_value = self._response("image/png")
+
+        self.assertTrue(_probe_image_url("https://example.test/logo.png"))
+
+    @patch("app.utils.asset_resolver.requests.head")
+    def test_returns_true_for_svg_with_charset_suffix(self, mock_head):
+        mock_head.return_value = self._response("image/svg+xml; charset=utf-8")
+
+        self.assertTrue(_probe_image_url("https://example.test/logo.svg"))
+
+    @patch("app.utils.asset_resolver.requests.head")
+    def test_returns_false_for_non_image_content_type(self, mock_head):
+        mock_head.return_value = self._response("text/html")
+
+        self.assertFalse(_probe_image_url("https://example.test/404"))
+
+    @patch("app.utils.asset_resolver.requests.head")
+    def test_returns_false_when_http_status_not_ok(self, mock_head):
+        mock_head.return_value = self._response(
+            "image/png",
+            raise_exc=requests.HTTPError("404 Not Found"),
+        )
+
+        self.assertFalse(_probe_image_url("https://example.test/missing.png"))
+
+    @patch("app.utils.asset_resolver.requests.head")
+    def test_returns_false_on_network_error(self, mock_head):
+        mock_head.side_effect = requests.ConnectionError("dns failure")
+
+        self.assertFalse(_probe_image_url("https://unreachable.test/logo.png"))
+
+    @patch("app.utils.asset_resolver.requests.head")
+    def test_follows_redirects_with_short_timeout(self, mock_head):
+        mock_head.return_value = self._response("image/png")
+
+        _probe_image_url("https://example.test/logo.png")
+
+        mock_head.assert_called_once_with(
+            "https://example.test/logo.png",
+            allow_redirects=True,
+            timeout=3,
+        )
+
+
+class TestAssetSrc(unittest.TestCase):
+    def test_returns_static_url_for_local_cache_path(self):
+        asset = {"cache": "cache/logo_abc.png", "external_url": None}
+
+        self.assertEqual(
+            asset_src(asset, _url_for_static),
+            "/static/cache/logo_abc.png",
+        )
+
+    def test_returns_absolute_url_unchanged_for_external_url(self):
+        # Regression: previously the template wrapped this through
+        # url_for('static', ...) and produced /static/https://... — a
+        # URL-in-URL the browser resolved against the dashboard host.
+        asset = {
+            "cache": None,
+            "external_url": "https://file.infinito.nexus/assets/img/logo.png",
+        }
+
+        self.assertEqual(
+            asset_src(asset, _url_for_static),
+            "https://file.infinito.nexus/assets/img/logo.png",
+        )
+
+    def test_external_url_wins_over_cache_when_both_present(self):
+        asset = {
+            "cache": "cache/logo.png",
+            "external_url": "https://override.test/logo.png",
+        }
+
+        self.assertEqual(
+            asset_src(asset, _url_for_static),
+            "https://override.test/logo.png",
+        )
+
+    def test_returns_empty_string_when_neither_field_is_set(self):
+        asset = {"cache": None, "external_url": None}
+
+        self.assertEqual(asset_src(asset, _url_for_static), "")
+
+    def test_returns_empty_string_for_none_or_empty_asset(self):
+        self.assertEqual(asset_src(None, _url_for_static), "")
+        self.assertEqual(asset_src({}, _url_for_static), "")
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_cache_manager.py

@@ -0,0 +1,72 @@
+import unittest
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from unittest.mock import Mock, patch
+
+import requests
+
+from app.utils.cache_manager import CacheManager
+
+
+class TestCacheManager(unittest.TestCase):
+    def test_init_creates_cache_directory(self):
+        with TemporaryDirectory() as temp_dir:
+            cache_dir = Path(temp_dir) / "cache"
+
+            self.assertFalse(cache_dir.exists())
+
+            CacheManager(str(cache_dir))
+
+            self.assertTrue(cache_dir.is_dir())
+
+    def test_clear_cache_removes_files_but_keeps_subdirectories(self):
+        with TemporaryDirectory() as temp_dir:
+            cache_dir = Path(temp_dir) / "cache"
+            nested_dir = cache_dir / "nested"
+            nested_dir.mkdir(parents=True)
+            file_path = cache_dir / "icon.png"
+            file_path.write_bytes(b"icon")
+
+            manager = CacheManager(str(cache_dir))
+            manager.clear_cache()
+
+            self.assertFalse(file_path.exists())
+            self.assertTrue(nested_dir.is_dir())
+
+    @patch("app.utils.cache_manager.requests.get")
+    def test_cache_file_downloads_and_stores_response(self, mock_get):
+        with TemporaryDirectory() as temp_dir:
+            manager = CacheManager(str(Path(temp_dir) / "cache"))
+            response = Mock()
+            response.headers = {"Content-Type": "image/svg+xml; charset=utf-8"}
+            response.iter_content.return_value = [b"<svg>ok</svg>"]
+            response.raise_for_status.return_value = None
+            mock_get.return_value = response
+
+            cached_path = manager.cache_file("https://example.com/logo/download")
+
+            self.assertIsNotNone(cached_path)
+            self.assertTrue(cached_path.startswith("cache/logo_"))
+            self.assertTrue(cached_path.endswith(".svg"))
+
+            stored_file = Path(manager.cache_dir) / Path(cached_path).name
+            self.assertEqual(stored_file.read_bytes(), b"<svg>ok</svg>")
+            mock_get.assert_called_once_with(
+                "https://example.com/logo/download",
+                stream=True,
+                timeout=5,
+            )
+
+    @patch("app.utils.cache_manager.requests.get")
+    def test_cache_file_returns_none_when_request_fails(self, mock_get):
+        with TemporaryDirectory() as temp_dir:
+            manager = CacheManager(str(Path(temp_dir) / "cache"))
+            mock_get.side_effect = requests.RequestException("network")
+
+            cached_path = manager.cache_file("https://example.com/icon.png")
+
+            self.assertIsNone(cached_path)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_check_hadolint_sarif.py

@@ -0,0 +1,49 @@
+import json
+import unittest
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+from utils import check_hadolint_sarif
+
+
+class TestCheckHadolintSarif(unittest.TestCase):
+    def test_main_returns_zero_for_clean_sarif(self):
+        sarif_payload = {
+            "runs": [
+                {
+                    "results": [],
+                }
+            ]
+        }
+
+        with TemporaryDirectory() as temp_dir:
+            sarif_path = Path(temp_dir) / "clean.sarif"
+            sarif_path.write_text(json.dumps(sarif_payload), encoding="utf-8")
+
+            exit_code = check_hadolint_sarif.main([str(sarif_path)])
+
+        self.assertEqual(exit_code, 0)
+
+    def test_main_returns_one_for_warnings_or_errors(self):
+        sarif_payload = {
+            "runs": [
+                {
+                    "results": [
+                        {"level": "warning"},
+                        {"level": "error"},
+                    ],
+                }
+            ]
+        }
+
+        with TemporaryDirectory() as temp_dir:
+            sarif_path = Path(temp_dir) / "warnings.sarif"
+            sarif_path.write_text(json.dumps(sarif_payload), encoding="utf-8")
+
+            exit_code = check_hadolint_sarif.main([str(sarif_path)])
+
+        self.assertEqual(exit_code, 1)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_compute_card_classes.py

@@ -0,0 +1,39 @@
+import unittest
+
+from app.utils.compute_card_classes import compute_card_classes
+
+
+class TestComputeCardClasses(unittest.TestCase):
+    def test_single_card_uses_full_width_classes(self):
+        lg_classes, md_classes = compute_card_classes([{"title": "One"}])
+
+        self.assertEqual(lg_classes, ["col-lg-12"])
+        self.assertEqual(md_classes, ["col-md-12"])
+
+    def test_two_cards_split_evenly(self):
+        lg_classes, md_classes = compute_card_classes([{}, {}])
+
+        self.assertEqual(lg_classes, ["col-lg-6", "col-lg-6"])
+        self.assertEqual(md_classes, ["col-md-6", "col-md-6"])
+
+    def test_three_cards_use_thirds(self):
+        lg_classes, md_classes = compute_card_classes([{}, {}, {}])
+
+        self.assertEqual(lg_classes, ["col-lg-4", "col-lg-4", "col-lg-4"])
+        self.assertEqual(md_classes, ["col-md-6", "col-md-6", "col-md-12"])
+
+    def test_five_cards_use_balanced_large_layout(self):
+        lg_classes, md_classes = compute_card_classes([{}, {}, {}, {}, {}])
+
+        self.assertEqual(
+            lg_classes,
+            ["col-lg-6", "col-lg-6", "col-lg-4", "col-lg-4", "col-lg-4"],
+        )
+        self.assertEqual(
+            md_classes,
+            ["col-md-6", "col-md-6", "col-md-6", "col-md-6", "col-md-12"],
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_configuration_resolver.py

@@ -0,0 +1,74 @@
+import unittest
+
+from app.utils.configuration_resolver import ConfigurationResolver
+
+
+class TestConfigurationResolver(unittest.TestCase):
+    def test_resolve_links_replaces_mapping_link_with_target_object(self):
+        config = {
+            "profiles": [
+                {"name": "Mastodon", "url": "https://example.com/@user"},
+            ],
+            "featured": {"link": "profiles.mastodon"},
+        }
+
+        resolver = ConfigurationResolver(config)
+        resolver.resolve_links()
+
+        self.assertEqual(
+            resolver.get_config()["featured"],
+            {"name": "Mastodon", "url": "https://example.com/@user"},
+        )
+
+    def test_resolve_links_expands_children_link_to_list_entries(self):
+        config = {
+            "accounts": {
+                "children": [
+                    {"name": "Matrix", "url": "https://matrix.example"},
+                    {"name": "Signal", "url": "https://signal.example"},
+                ]
+            },
+            "navigation": {
+                "children": [
+                    {"link": "accounts.children"},
+                ]
+            },
+        }
+
+        resolver = ConfigurationResolver(config)
+        resolver.resolve_links()
+
+        self.assertEqual(
+            resolver.get_config()["navigation"]["children"],
+            [
+                {"name": "Matrix", "url": "https://matrix.example"},
+                {"name": "Signal", "url": "https://signal.example"},
+            ],
+        )
+
+    def test_resolve_links_rejects_non_list_children(self):
+        config = {"navigation": {"children": {"name": "Invalid"}}}
+
+        resolver = ConfigurationResolver(config)
+
+        with self.assertRaises(ValueError):
+            resolver.resolve_links()
+
+    def test_find_entry_handles_case_and_space_insensitive_paths(self):
+        config = {
+            "Social Networks": {
+                "children": [
+                    {"name": "Friendica", "url": "https://friendica.example"},
+                ]
+            }
+        }
+
+        resolver = ConfigurationResolver(config)
+
+        entry = resolver._find_entry(config, "socialnetworks.friendica", False)
+
+        self.assertEqual(entry["url"], "https://friendica.example")
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_export_runtime_requirements.py

@@ -0,0 +1,45 @@
+import unittest
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from unittest.mock import patch
+
+from utils import export_runtime_requirements
+
+
+class TestExportRuntimeRequirements(unittest.TestCase):
+    def test_load_runtime_requirements_reads_project_dependencies(self):
+        pyproject_content = """
+[project]
+dependencies = [
+    "flask",
+    "requests>=2",
+]
+""".lstrip()
+
+        with TemporaryDirectory() as temp_dir:
+            pyproject_path = Path(temp_dir) / "pyproject.toml"
+            pyproject_path.write_text(pyproject_content, encoding="utf-8")
+
+            requirements = export_runtime_requirements.load_runtime_requirements(
+                pyproject_path
+            )
+
+        self.assertEqual(requirements, ["flask", "requests>=2"])
+
+    def test_main_prints_requirements_from_selected_pyproject(self):
+        pyproject_content = """
+[project]
+dependencies = [
+    "pyyaml",
+]
+""".lstrip()
+
+        with TemporaryDirectory() as temp_dir:
+            pyproject_path = Path(temp_dir) / "pyproject.toml"
+            pyproject_path.write_text(pyproject_content, encoding="utf-8")
+
+            with patch("builtins.print") as mock_print:
+                exit_code = export_runtime_requirements.main([str(pyproject_path)])
+
+        self.assertEqual(exit_code, 0)
+        mock_print.assert_called_once_with("pyyaml")

tests/unit/test_i18n.py

@@ -0,0 +1,217 @@
+import re
+import shutil
+import tempfile
+import unittest
+from pathlib import Path
+
+import yaml
+
+from app.utils import i18n
+
+
+class TestNegotiate(unittest.TestCase):
+    def test_regional_tag_beats_a_lower_ranked_exact_match(self):
+        self.assertEqual(i18n.negotiate([("de-DE", 1.0), ("en", 0.8)]), "de")
+
+    def test_underscore_separated_tag_is_accepted(self):
+        self.assertEqual(i18n.negotiate([("pt_BR", 1.0)]), "pt")
+
+    def test_highest_quality_supported_tag_wins(self):
+        self.assertEqual(
+            i18n.negotiate([("xx", 1.0), ("fr", 0.9), ("es", 0.5)]),
+            "fr",
+        )
+
+    def test_unsupported_tags_fall_back_to_the_default(self):
+        self.assertEqual(i18n.negotiate([("xx", 1.0)]), "en")
+        self.assertEqual(i18n.negotiate([], default="de"), "de")
+
+    def test_a_refused_language_is_not_selected(self):
+        self.assertEqual(i18n.negotiate([("de", 0.0)]), "en")
+
+    def test_the_first_of_two_equal_tags_wins(self):
+        self.assertEqual(i18n.negotiate([("fr", 0.9), ("es", 0.9)]), "fr")
+
+
+class TestDirection(unittest.TestCase):
+    def test_every_right_to_left_language_is_marked(self):
+        for code in ("ar", "dv", "fa", "he", "ks", "ps", "sd", "ug", "ur", "yi"):
+            with self.subTest(code=code):
+                self.assertEqual(i18n.direction(code), "rtl")
+
+    def test_other_languages_are_left_to_right(self):
+        for code in set(i18n.LANGUAGES) - set(i18n.RTL_LANGUAGES):
+            with self.subTest(code=code):
+                self.assertEqual(i18n.direction(code), "ltr")
+
+
+class TestTranslateTree(unittest.TestCase):
+    def setUp(self):
+        self.addCleanup(i18n._catalogs.clear)
+        i18n._catalogs["xx"] = {"A card": "Eine Karte", "Pictures": "Bilder"}
+
+    def test_only_translatable_keys_are_replaced(self):
+        tree = {
+            "cards": [
+                {
+                    "title": "Pictures",
+                    "text": "A card",
+                    "url": "A card",
+                    "icon": {"class": "Pictures"},
+                }
+            ]
+        }
+
+        translated = i18n.translate_tree(tree, "xx")
+
+        card = translated["cards"][0]
+        self.assertEqual(card["title"], "Bilder")
+        self.assertEqual(card["text"], "Eine Karte")
+        self.assertEqual(card["url"], "A card")
+        self.assertEqual(card["icon"]["class"], "Pictures")
+
+    def test_unknown_strings_keep_their_source_value(self):
+        translated = i18n.translate_tree({"description": "Untranslated"}, "xx")
+
+        self.assertEqual(translated["description"], "Untranslated")
+
+    def test_source_tree_is_left_untouched(self):
+        tree = {"name": "Pictures"}
+
+        i18n.translate_tree(tree, "xx")
+
+        self.assertEqual(tree["name"], "Pictures")
+
+    def test_non_string_leaves_survive(self):
+        tree = {"name": 1, "text": None, "info": True}
+
+        self.assertEqual(i18n.translate_tree(tree, "xx"), tree)
+
+
+class TestReadCatalog(unittest.TestCase):
+    def setUp(self):
+        self.directory = Path(tempfile.mkdtemp())
+        self.addCleanup(shutil.rmtree, self.directory, True)
+        self.path = self.directory / "de.yaml"
+
+    def _read(self, text):
+        self.path.write_text(text, encoding="utf-8")
+        with self.assertLogs(level="WARNING"):
+            return i18n.read_catalog(self.path)
+
+    def test_absent_file_is_an_empty_catalog(self):
+        self.assertEqual(i18n.read_catalog(self.directory / "missing.yaml"), {})
+
+    def test_unparsable_yaml_is_an_empty_catalog(self):
+        self.assertEqual(self._read("Close: [unclosed"), {})
+
+    def test_tab_indentation_is_an_empty_catalog(self):
+        self.assertEqual(self._read("a:\n\tb: 1"), {})
+
+    def test_non_mapping_document_is_an_empty_catalog(self):
+        self.assertEqual(self._read("- a\n- b"), {})
+
+    def test_a_non_utf8_catalog_is_an_empty_catalog(self):
+        self.path.write_bytes(b"\xffClose: Schliessen\n")
+
+        with self.assertLogs(level="WARNING"):
+            self.assertEqual(i18n.read_catalog(self.path), {})
+
+    def test_a_directory_at_the_catalog_path_is_an_empty_catalog(self):
+        (self.directory / "sub.yaml").mkdir()
+
+        with self.assertLogs(level="WARNING"):
+            self.assertEqual(i18n.read_catalog(self.directory / "sub.yaml"), {})
+
+    def test_non_string_entries_are_dropped(self):
+        self.path.write_text(
+            "Close: 42\nOpen:\nCopy: yes\nImprint: Impressum\n", encoding="utf-8"
+        )
+
+        self.assertEqual(i18n.read_catalog(self.path), {"Imprint": "Impressum"})
+
+
+class TestCatalogMerge(unittest.TestCase):
+    def setUp(self):
+        directory = Path(tempfile.mkdtemp())
+        self.addCleanup(shutil.rmtree, directory, True)
+        (directory / "ui").mkdir()
+        (directory / "content").mkdir()
+
+        self.addCleanup(setattr, i18n, "UI_DIR", i18n.UI_DIR)
+        self.addCleanup(setattr, i18n, "CONTENT_DIR", i18n.CONTENT_DIR)
+        self.addCleanup(i18n.clear_catalogs)
+        i18n.UI_DIR = directory / "ui"
+        i18n.CONTENT_DIR = directory / "content"
+        i18n.clear_catalogs()
+
+    def test_the_content_catalog_overrides_the_shipped_interface_string(self):
+        (i18n.UI_DIR / "de.yaml").write_text(
+            "Close: Schliessen\nImprint: Impressum\n", encoding="utf-8"
+        )
+        (i18n.CONTENT_DIR / "de.yaml").write_text("Close: Zumachen\n", encoding="utf-8")
+
+        self.assertEqual(
+            i18n.catalog("de"), {"Close": "Zumachen", "Imprint": "Impressum"}
+        )
+
+
+class TestShippedCatalogs(unittest.TestCase):
+    def test_every_iso_639_1_language_is_offered(self):
+        self.assertEqual(len(i18n.LANGUAGES), 184)
+        self.assertEqual(i18n.SOURCE_LANGUAGE, next(iter(i18n.LANGUAGES)))
+        self.assertGreaterEqual(
+            set(i18n.LANGUAGES), {"en", "de", "zh", "ar", "he", "vo", "za", "cu"}
+        )
+
+    def test_every_display_name_is_filled_in(self):
+        blank = [code for code, name in i18n.LANGUAGES.items() if not name.strip()]
+
+        self.assertFalse(blank, f"No display name for: {blank}")
+
+    def test_every_code_is_usable_in_the_route_converter(self):
+        offenders = [
+            code for code in i18n.LANGUAGES if not re.fullmatch(r"[a-z]+", code)
+        ]
+
+        self.assertFalse(offenders, f"Not usable in the route converter: {offenders}")
+
+    def test_every_shipped_catalog_names_a_known_language(self):
+        stray = [
+            path.stem
+            for path in i18n.UI_DIR.glob("*.yaml")
+            if path.stem not in i18n.LANGUAGES or path.stem == i18n.SOURCE_LANGUAGE
+        ]
+
+        self.assertFalse(stray, f"Catalogue for an unknown language: {stray}")
+
+    def test_ui_catalogs_cover_exactly_the_interface_strings(self):
+        expected = set(i18n.UI_STRINGS)
+        mismatched = {}
+
+        for path in sorted(i18n.UI_DIR.glob("*.yaml")):
+            code = path.stem
+            entries = yaml.safe_load(path.read_text(encoding="utf-8"))
+            if set(entries) != expected:
+                mismatched[code] = {
+                    "missing": sorted(expected - set(entries)),
+                    "unexpected": sorted(set(entries) - expected),
+                }
+
+        self.assertFalse(mismatched, f"UI catalogues out of sync: {mismatched}")
+
+    def test_ui_strings_of_the_source_language_are_the_source(self):
+        self.assertEqual(
+            i18n.ui_strings("en"),
+            {source: source for source in i18n.UI_STRINGS},
+        )
+
+    def test_ui_strings_are_translated_for_a_shipped_language(self):
+        strings = i18n.ui_strings("de")
+
+        self.assertEqual(strings["Close"], "Schließen")
+        self.assertEqual(strings["Imprint"], "Impressum")
+
+
+if __name__ == "__main__":
+    unittest.main()