feat(i18n): spec 019 language packs: catalog, checker, backend, module translations and designs

.devcontainer/post-create.sh

@@ -76,7 +76,7 @@ log "fetching envtest binaries for K8s 1.36.2"
 # ---------- Go module cache warmup ----------
 # Go modules from go.work. Derived from 'use' entries in go.work.
 # Keep in sync with go.work when adding/removing modules.
-for m in agent api audit-syslog-bridge capture-sidecar gameaction gameproto mcp-server netguard operator sentinel svcutil telemetry-receiver telemetryschema test/e2e tunnel; do
+for m in agent api audit-syslog-bridge capture-sidecar gameaction gameproto i18n mcp-server netguard operator sentinel svcutil telemetry-receiver telemetryschema test/e2e tunnel; do
 	log "go mod download ($m)"
 	( cd "$m" && go mod download )
 done

.github/dependabot.yml

@@ -186,6 +186,20 @@ updates:
       telemetryschema-minor-patch:
         update-types: ["minor", "patch"]
 
+  - package-ecosystem: "gomod"
+    directory: "/i18n"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "03:00"
+    commit-message:
+      prefix: "chore(deps)"
+      include: "scope"
+    open-pull-requests-limit: 5
+    groups:
+      i18n-minor-patch:
+        update-types: ["minor", "patch"]
+
   - package-ecosystem: "gomod"
     directory: "/telemetry-receiver"
     schedule:

.github/workflows/ci.yaml

@@ -127,6 +127,7 @@ jobs:
               - 'audit-syslog-bridge/**'
               - 'telemetry-receiver/**'
               - 'telemetryschema/**'
+              - 'i18n/**'
               - 'sentinel/**'
               - 'mcp-server/**'
               - 'capture-sidecar/**'
@@ -143,7 +144,9 @@ jobs:
               - 'hack/check-govulncheck_test.sh'
               - 'hack/testdata/govulncheck/**'
             web:
+              # Language packs feed the dashboard build and the i18n checks in the web job.
               - 'web/**'
+              - 'i18n/**'
             charts:
               - 'charts/**'
               # The chart embeds a copy of the root signing key; the drift
@@ -698,7 +701,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        module: [netguard, gameaction, gameproto, telemetryschema, operator, agent, api, sentinel, audit-syslog-bridge, telemetry-receiver, mcp-server, capture-sidecar, svcutil, tunnel, gp-module, test/e2e]
+        module: [netguard, gameaction, gameproto, telemetryschema, i18n, operator, agent, api, sentinel, audit-syslog-bridge, telemetry-receiver, mcp-server, capture-sidecar, svcutil, tunnel, gp-module, test/e2e]
         exclude: ${{ fromJSON(needs.changes.outputs.lint-exclude) }}
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -777,7 +780,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        module: [netguard, gameaction, gameproto, telemetryschema, operator, api, agent, audit-syslog-bridge, telemetry-receiver, sentinel, mcp-server, capture-sidecar, svcutil, tunnel, gp-module]
+        module: [netguard, gameaction, gameproto, telemetryschema, i18n, operator, api, agent, audit-syslog-bridge, telemetry-receiver, sentinel, mcp-server, capture-sidecar, svcutil, tunnel, gp-module]
         exclude: ${{ fromJSON(needs.changes.outputs.go-exclude) }}
         arch: [amd64, arm64]
     steps:
@@ -890,6 +893,67 @@ jobs:
       - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
         with: { node-version: "24", cache: "npm", cache-dependency-path: web/package-lock.json }
       - run: npm ci
+      - uses: ./.github/actions/go-cache
+        with:
+          key-suffix: web-i18n
+      - name: i18n language manifest
+        # The listing rule (80% complete, ltr, not en-XA) lives in the shared
+        # Go checker, so the manifest the dashboard build reads comes from it.
+        run: npm run i18n:manifest
+      - name: i18n checks
+        working-directory: .
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }}
+        run: |
+          set -euo pipefail
+          (cd web && npm run i18n:extract-only)
+          (cd api && go run ./cmd/messages-export > "$RUNNER_TEMP/registry.json")
+          (cd operator && go run ./hack/condition-ids -check -app ../i18n/locales/en/app.json -ids "$RUNNER_TEMP/condition-ids.txt")
+          {
+            jq -r 'keys[]' web/src/generated/i18n/extracted.json
+            jq -r '.[].id' "$RUNNER_TEMP/registry.json"
+            cat "$RUNNER_TEMP/condition-ids.txt"
+          } | sort -u > "$RUNNER_TEMP/used-ids.txt"
+          base_flag=()
+          if [ -n "${BASE_SHA:-}" ] && [ "$BASE_SHA" != "0000000000000000000000000000000000000000" ]; then
+            if git fetch --no-tags --depth=1 origin "$BASE_SHA" 2>/dev/null \
+              && git cat-file -e "$BASE_SHA:i18n/locales" 2>/dev/null; then
+              mkdir -p "$RUNNER_TEMP/base"
+              git archive "$BASE_SHA" i18n/locales | tar -x -C "$RUNNER_TEMP/base"
+              base_flag=(--base "$RUNNER_TEMP/base/i18n/locales")
+            fi
+          fi
+          cd i18n
+          go run ./cmd/i18n-check \
+            --extracted ../web/src/generated/i18n/extracted.json \
+            --registry "$RUNNER_TEMP/registry.json" --check-server \
+            --used-ids "$RUNNER_TEMP/used-ids.txt" \
+            "${base_flag[@]}" \
+            --summary "$GITHUB_STEP_SUMMARY" \
+            locales
+      - name: i18n-check self-test on seeded defective packs
+        # SC-007: every fixture must make the checker fail with exactly its
+        # own finding code (needs-review is a notice, so it passes).
+        working-directory: i18n
+        run: |
+          set -euo pipefail
+          go build -o "$RUNNER_TEMP/i18n-check" ./cmd/i18n-check
+          for dir in testdata/defective/*/; do
+            code=$(basename "$dir")
+            args=()
+            if [ -f "$dir/args" ]; then
+              read -r -a args < <(sed "s#{dir}#${dir%/}#g" "$dir/args")
+            fi
+            set +e
+            out=$("$RUNNER_TEMP/i18n-check" "${args[@]}" "${dir%/}")
+            status=$?
+            set -e
+            want=1; [ "$code" = needs-review ] && want=0
+            if [ "$status" -ne "$want" ] || ! grep -q "\[$code\]" <<<"$out"; then
+              echo "::error::fixture $code: exit $status (want $want), output:"; echo "$out"; exit 1
+            fi
+            echo "ok $code"
+          done
       - name: eslint
         run: npm run lint
       - run: npm run build

.github/workflows/publish-edge.yaml

@@ -29,6 +29,7 @@ on:
       - "gameaction/**"
       - "gameproto/**"
       - "telemetryschema/**"
+      - "i18n/**"
       - "svcutil/**"
       - "gp-module/**"
       - "audit-syslog-bridge/**"

.github/workflows/visual-diff.yaml

@@ -5,11 +5,13 @@ on:
     branches: [master]
     paths:
       - 'web/**'
+      - 'i18n/locales/**'
       - 'assets/design-export/**'
       - '.github/workflows/visual-diff.yaml'
   pull_request:
     paths:
       - 'web/**'
+      - 'i18n/locales/**'
       - 'assets/design-export/**'
       - '.github/workflows/visual-diff.yaml'
   workflow_dispatch:
@@ -80,3 +82,51 @@ jobs:
           path: web/e2e/screenshots/*.png
           retention-days: 14
           if-no-files-found: warn
+
+  pseudo-locale:
+    name: en-XA screenshots (spec 019)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    timeout-minutes: 30
+    defaults:
+      run:
+        working-directory: web
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: "24"
+          cache: "npm"
+          cache-dependency-path: web/package-lock.json
+
+      - name: install dependencies
+        run: npm ci
+
+      - name: playwright browser cache
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('web/package-lock.json') }}
+          restore-keys: |
+            playwright-${{ runner.os }}-${{ runner.arch }}-
+
+      - name: install chromium
+        run: npx playwright install --with-deps chromium
+
+      - name: capture en-XA screenshots and check clipping
+        run: npm run screenshots:pseudo
+
+      - name: upload en-XA captures and clipping report
+        if: always()
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: en-XA-screenshots
+          path: |
+            web/test-results/en-XA
+            web/playwright-report
+          retention-days: 14
+          if-no-files-found: warn

.gitignore

@@ -25,6 +25,15 @@ web/coverage/
 web/playwright-report/
 web/test-results/
 web/website-screenshots/
+# Generated i18n artifacts (compiled catalogs, extracted messages, language manifest)
+web/src/generated/
+# Registry snapshot written by `make i18n-sync` and consumed by i18n-check
+i18n/.registry.json
+# Condition ids and used-id list written by `make check-i18n` (spec 019)
+i18n/.condition-ids.txt
+i18n/.used-ids.txt
+# Filtered language packs written by i18n-check --valid-out for the dashboard build
+i18n/.valid/
 web/e2e/.portforward.pid
 *.log
 .npmrc.local

CHANGELOG.md

@@ -153,6 +153,36 @@ reaches `1.0.0`. Pre-1.0 minor versions may contain breaking changes.
 - **Nuclear Option player lists are structured:** the agent's player output
   for JSON player lists now includes an entry per player (`steamId` and
   `faction`), which the API uses for display-name lookup.
+- **Language selection and translations (spec 019):** the dashboard can be
+  shown in another language. A user's language choice is saved to the account (or
+  to the browser when signed out), and an admin sets the instance default. Languages are
+  shared packs under `i18n/locales/`; a language is listed once its pack is at
+  least 80% translated, and anything missing falls back to English. French is
+  the first pack and is listed once it reaches 80%.
+  Dates, numbers and relative times follow the active language. A pseudo
+  language (`en-XA`) exists for maintainers behind `VITE_I18N_PSEUDO=1` and is
+  never listed in a release. See [`docs/translating.md`](docs/translating.md).
+- **Translated server messages (opt-in `problem+json`):** API errors are sent
+  as `application/problem+json` with a stable `messageId` and arguments only
+  when the request lists that type in `Accept`; every other client keeps the
+  unchanged English plain-text body. The dashboard opts in and shows the
+  message in the active language. Game server condition messages carry
+  `status.conditionArgs` so the dashboard can translate them too; the English
+  `message` is unchanged.
+- **Notification language per destination:** each notification destination
+  has an optional `language`; notifications and test sends to Discord, email
+  and webhooks are rendered in it, and destinations with none use the
+  instance default. Webhook payloads gain additive `language`, `title` and
+  `text` fields; existing fields are unchanged.
+- **Module translations:** a module can ship `locales/<tag>.json` next to
+  `module.yaml` (OCI layer type `application/vnd.gameplane.module.locale.v1+json`
+  and the same files in every other source). The operator validates them on
+  install, stores the valid entries in a `<template>-locales` ConfigMap and
+  reports problems as the `LocalesValid` condition; install never fails
+  because of translations. Each file is read up to 900 KiB and all of a
+  bundle's files together up to 4 MiB. `gp-module i18n extract|stamp` and
+  `gp-module validate` support authoring. See
+  [`docs/module-authoring.md`](docs/module-authoring.md).
 
 ### Changed
 

CLAUDE.md

@@ -36,6 +36,7 @@ netguard/            SSRF dial-guard: IsAllowed (operator module sources, API si
 gameaction/          console-injection guard + command renderer (api, agent)
 gameproto/           Minecraft/Terraria handshake parser (sentinel)
 telemetryschema/     shared telemetry report contract (api, telemetry-receiver)
+i18n/                shared language packs, ICU formatter, pack validator, i18n-check (api, web, operator, gp-module)
 gp-module/           module authoring CLI: init/validate/preview/package
 operator/            controller-runtime operator
   api/v1alpha1/      CRD types (edit here, then `make generate manifests`); zz_generated.deepcopy.go GENERATED
@@ -60,7 +61,7 @@ test/e2e/            Kind E2E suite (//go:build e2e)
 docs/                architecture, security, modules
 design.pen           canonical Pencil dashboard design
 signing/             cosign public keys, dated legacy key + cross-signature (image + module)
-go.work              links all 16 Go modules (incl. test/e2e)
+go.work              links all 17 Go modules (incl. test/e2e)
 Makefile             canonical task runner
 ```
 
@@ -75,7 +76,7 @@ After cloning: `git submodule update --init` (`modules/` required for `make dev-
 - **E2E conventions:** register new tests in `test/e2e/buckets.sh`; `t.Parallel()` + unique names; guard shared resources (`ociPushMu` for module pushes, `ensureResticRepo(t)` for shared backup repos). Rate limits per cluster: IP burst 10 (5/min), user burst 6 (3/min) — cap an API bucket at ~7 admin logins.
 - **Lint:** `make lint` = gofmt, go vet, golangci-lint, ESLint, `check-specs`, `check-doc-versions`, `check-links`.
 
-**Coverage minimums:** netguard 91, gameaction 91, gameproto 90, telemetryschema 90, gp-module 80, operator 72, api 80, agent 90, svcutil 90; audit-syslog-bridge, telemetry-receiver, sentinel, capture-sidecar, mcp-server, tunnel 70; web 92 lines / 76 functions / 82 branches / 92 statements.
+**Coverage minimums:** netguard 91, gameaction 91, gameproto 90, telemetryschema 90, i18n 90, gp-module 80, operator 72, api 80, agent 90, svcutil 90; audit-syslog-bridge, telemetry-receiver, sentinel, capture-sidecar, mcp-server, tunnel 70; web 92 lines / 76 functions / 82 branches / 92 statements.
 
 ## Core rules
 
@@ -116,6 +117,7 @@ After cloning: `git submodule update --init` (`modules/` required for `make dev-
 | gameaction | Go | validates console input against schemas; escapes injection |
 | gameproto | Go | Minecraft/Terraria wire parser for connection filtering |
 | telemetryschema | Go | stdlib-only shared telemetry report contract: types, strict decode, official module catalog, report signing (api, telemetry-receiver) |
+| i18n | Go | shared language packs (`go:embed`), ICU MessageFormat subset, pack validator, `i18n-check` CI tool (api, web, operator, gp-module) |
 | gp-module | Go | module CLI: scaffold, offline validate, dry-run preview, OCI package |
 | svcutil | Go | stdlib-only env + graceful shutdown (`RunHTTP`) |
 | operator | Go, controller-runtime | authoritative reconciler for 9 CRDs (`GameServer`, `GameTemplate`, …) |

Makefile

@@ -40,7 +40,7 @@ KUBECONFIG_ENV :=
 KUBE_CONTEXT   := kind-$(KIND_CLUSTER)
 endif
 
-GO_MODULES     := netguard gameaction gameproto telemetryschema gp-module operator api agent audit-syslog-bridge telemetry-receiver sentinel mcp-server capture-sidecar svcutil tunnel
+GO_MODULES     := netguard gameaction gameproto telemetryschema i18n gp-module operator api agent audit-syslog-bridge telemetry-receiver sentinel mcp-server capture-sidecar svcutil tunnel
 GO_INTEGRATION_MODULES := operator api
 
 # test/e2e is a separate module (its own go.mod, excluded from the coverage
@@ -267,6 +267,21 @@ test-features-sync: ## Run the fixture tests for hack/check-features-sync.sh
 check-telemetry-catalog: ## Verify telemetryschema/catalog.txt matches the chart's official module list
 	hack/check-telemetry-catalog.sh
 
+.PHONY: i18n-sync
+i18n-sync: ## Write the API message registry (server.* and notify.*) and the operator condition.* ids into the English reference (i18n/locales/en/app.json)
+	cd api && go run ./cmd/messages-export > ../i18n/.registry.json
+	cd i18n && go run ./cmd/i18n-check --registry .registry.json --sync-server locales
+	rm -f i18n/.registry.json
+	cd operator && go run ./hack/condition-ids -app ../i18n/locales/en/app.json
+
+.PHONY: check-i18n
+check-i18n: ## Verify language packs, server.*, notify.*, operator condition.* drift, dashboard extraction drift and unused reference ids (spec 019)
+	cd web && npm run i18n:extract-only
+	cd operator && go run ./hack/condition-ids -check -app ../i18n/locales/en/app.json -ids ../i18n/.condition-ids.txt
+	cd api && go run ./cmd/messages-export > ../i18n/.registry.json
+	cd i18n && { jq -r 'keys[]' ../web/src/generated/i18n/extracted.json; jq -r '.[].id' .registry.json; cat .condition-ids.txt; } | sort -u > .used-ids.txt
+	cd i18n && status=0; go run ./cmd/i18n-check --extracted ../web/src/generated/i18n/extracted.json --registry .registry.json --check-server --used-ids .used-ids.txt locales || status=$$?; rm -f .registry.json .condition-ids.txt .used-ids.txt; exit $$status
+
 .PHONY: check-dev-load-images
 check-dev-load-images: ## Verify `dev-load` loads every image `images` builds
 	hack/check-dev-load-images.sh
@@ -281,7 +296,7 @@ test-up-registry: ## Run the fixture tests for deploy/kind/up.sh's registry/cont
 	hack/test-up-registry.sh
 
 .PHONY: lint
-lint: check-doc-versions check-links check-features-sync check-specs check-telemetry-catalog check-dev-load-images check-coverage-gaps test-up-registry lint-go lint-web ## Run all linters
+lint: check-doc-versions check-links check-features-sync check-specs check-telemetry-catalog check-i18n check-dev-load-images check-coverage-gaps test-up-registry lint-go lint-web ## Run all linters
 
 .PHONY: lint-go
 lint-go: ## Run golangci-lint across all modules

README.md

@@ -303,6 +303,9 @@ Design changes go through `design.pen` (Pencil) before any UI code is
 written. See [`docs/contributing.md`](docs/contributing.md) for the
 full guide: code style, test tiers, and the PR process.
 
+Translations are welcome. See [`docs/translating.md`](docs/translating.md)
+to add or improve a language pack.
+
 ## License
 
 [AGPL-3.0-or-later](./LICENSE). Any network-accessible deployment of a

api/Dockerfile

@@ -1,13 +1,14 @@
 FROM --platform=$BUILDPLATFORM golang:1.27-alpine AS build
 WORKDIR /src
 
-# netguard, gameaction, gp-module, and telemetryschema are in-repo modules the API depends
-# on via local replaces (../netguard, ../gameaction, ../gp-module, ../telemetryschema);
+# netguard, gameaction, gp-module, telemetryschema, and i18n are in-repo modules the API depends
+# on via local replaces (../netguard, ../gameaction, ../gp-module, ../telemetryschema, ../i18n);
 # copy them first so `go mod download` and the build resolve them.
 COPY netguard/ ./netguard/
 COPY gameaction/ ./gameaction/
 COPY gp-module/ ./gp-module/
 COPY telemetryschema/ ./telemetryschema/
+COPY i18n/ ./i18n/
 COPY api/go.mod api/go.sum* ./api/
 WORKDIR /src/api
 RUN go mod download

api/cmd/main.go

@@ -325,6 +325,10 @@ func main() {
 		// registry per request so config saves apply without a restart.
 		// No version/host/count — login-privacy.
 		r.Get("/providers", handlers.AuthProvidersHandler(authRegistry))
+		// Pre-auth: the instance default language for the login page. Only the
+		// tag is returned, never more (login privacy); not rate-limited, like
+		// /providers.
+		r.Get("/locale", handlers.AuthLocaleHandler(store))
 		// Rate-limit /login specifically — argon2id is ~200 ms of
 		// single-core CPU per attempt, so an unlimited path invites a
 		// trivial DoS.

api/cmd/messages-export/main.go

@@ -0,0 +1,19 @@
+// Command messages-export writes the API message registry as JSON to stdout,
+// together with the notify.* notification text. The i18n-sync Makefile target
+// feeds the output to i18n-check.
+package main
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/GameplanePanel/gameplane/api/internal/messages"
+	"github.com/GameplanePanel/gameplane/api/internal/notify"
+)
+
+func main() {
+	if err := messages.ExportJSON(os.Stdout, notify.Messages()...); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}