feat: internationalise the app with english and british

Signed-off-by: Simon Emms <simon@simonemms.com>

Author: mrsimonemms

.pre-commit-config.yaml

@@ -10,6 +10,7 @@ repos:
         args:
           - --autofix
           - --no-sort-keys
+          - --no-ensure-ascii
       - id: check-json
       - id: check-yaml
         exclude: charts

CLAUDE.md

@@ -38,6 +38,7 @@ tooling over novelty or abstraction.
 - **Runtime:** Node.js (Docker)
 - **Linting:** ESLint (flat config)
 - **Formatting:** Prettier (project-defined config)
+- **i18n:** i18next (required)
 
 Do not:
 
@@ -49,6 +50,70 @@ Do not:
 
 ---
 
+## Internationalisation (i18n) requirements (mandatory)
+
+This project **must** use an established i18n library, not a custom implementation.
+
+### Library
+
+- Use **i18next** with a Svelte-compatible integration (do not build our own
+  i18n layer).
+- Keep translations in JSON resource files.
+- Prefer **literal Unicode characters** in i18n JSON (e.g. `…`, `£`, `→`)
+  over HTML entities (e.g. `…`) or escaped codepoints (e.g. `\u2026`)
+  unless a tool forces escaping.
+
+### Supported locales (for now)
+
+- `en` (English, International) — default
+- `en-GB` (English, British)
+
+### Locale selection priority (authoritative)
+
+1. User-selected locale in the UI (persisted)
+2. Browser language headers (e.g. `navigator.languages`)
+3. Fallback to `en`
+
+### Fallback behaviour
+
+- `en-GB` **must** fall back to `en` for missing keys so British English only
+  needs to override deltas.
+- Do not duplicate `en` strings into `en-GB` unless the wording/spelling
+  genuinely differs.
+
+### Hard rule: no new plain text in the UI
+
+- **Do not introduce new user-visible strings inline** in Svelte components,
+  stores, routes, or helpers.
+- Any new user-visible text **must** be added as an i18n string key and rendered
+  via `t(...)`.
+- This includes:
+  - Button labels, headings, breadcrumbs, empty states
+  - Toasts, alerts, errors shown to users
+  - Inspector labels and field names
+  - Modal titles and helper text
+
+Allowed exceptions (narrow):
+
+- User data (workflow names, task names, branch labels, etc.)
+- Debug-only `console.*` output (must not be user-facing)
+
+### Key naming + structure guidance
+
+- Use a predictable, boring hierarchy (e.g. `editor.*`, `sidebar.*`, `inspector.*`,
+  `errors.*`, `actions.*`).
+- Prefer stable keys over copy-based keys (do not bake full sentences into key
+  names).
+- Keep strings short and composable where it helps reuse, but do not over-abstract.
+
+### Testing expectation
+
+- Any feature work that introduces UI text must include the corresponding `en` key.
+- If a string is British-specific, add it to `en-GB`; otherwise only `en` is
+  required.
+
+---
+
 ## Runtime & deployment assumptions
 
 - The app runs as a **Node server**, not a static site
@@ -210,6 +275,8 @@ Validation errors must be:
 - Inspector panels edit **node config**, not graph topology
 - UI must reflect validation state clearly
 - Avoid auto-magic graph rewrites
+- All user-visible UI strings must come from i18n resources via `t(...)` (no
+  inline copy).
 
 ---
 
@@ -454,3 +521,5 @@ When asked to “build” something:
 
 - Start with the smallest viable, end-to-end slice
 - Prefer scaffolding that can grow over finished-looking systems
+- Add or extend tests to lock in behaviour
+- All new user-visible UI text must use i18n (i18next), not inline strings

package-lock.json

@@ -35,6 +35,7 @@
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-svelte": "^3.15.1",
     "globals": "^17.4.0",
+    "i18next": "^25.8.18",
     "js-yaml": "^4.1.1",
     "prettier": "^3.8.1",
     "prettier-plugin-svelte": "^3.5.1",

package.json

@@ -0,0 +1,77 @@
+/*
+ * Copyright 2025 - 2026 Zigflow authors <https://github.com/zigflow/studio/graphs/contributors>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+// Zigflow Studio — i18n module
+//
+// Uses a .svelte.ts file so that module-level $state is available.
+// The reactive version counter `_v` is incremented on every locale change;
+// any Svelte template expression that calls t() will re-evaluate because
+// t() reads _v, creating a reactive dependency.
+import i18next from 'i18next';
+
+import enGbJson from './messages/en-GB.json';
+import enJson from './messages/en.json';
+
+export type { Locale } from './locales';
+export { parseAcceptLanguage, resolveLocale } from './locales';
+
+// Module-level reactive version counter.  Incrementing this causes every
+// call to t() that appears in a Svelte reactive context to re-evaluate.
+let _v = $state(0);
+
+/**
+ * Initialise (or change language of) the i18next singleton.
+ * Safe to call multiple times — idempotent for the same locale.
+ */
+export function initI18n(locale: string): void {
+  if (i18next.isInitialized) {
+    i18next.changeLanguage(locale);
+  } else {
+    // init() is synchronous when resources are provided directly.
+    i18next.init({
+      lng: locale,
+      resources: {
+        en: { translation: enJson },
+        'en-GB': { translation: enGbJson },
+      },
+      fallbackLng: {
+        'en-GB': ['en'],
+        default: ['en'],
+      },
+      interpolation: { escapeValue: false },
+    });
+  }
+  // Bump the reactive counter so every t() call re-evaluates.
+  _v += 1;
+}
+
+/**
+ * Translate a dot-separated key.
+ *
+ * Reads the reactive `_v` counter unconditionally so that Svelte re-evaluates
+ * any template expression containing t() whenever the locale changes —
+ * including the first call to initI18n() after the component mounts.
+ *
+ * `ver < 0` is structurally impossible (counter only increments from 0) but
+ * the comparison keeps ESLint quiet while preserving the reactive read.
+ */
+export function t(key: string, options?: Record<string, unknown>): string {
+  // Read _v unconditionally so Svelte tracks it as a dependency even before
+  // i18next is initialised.  Short-circuiting `|| _v < 0` would skip the read
+  // when isInitialized is false, losing the dependency.
+  const ver = _v;
+  if (!i18next.isInitialized || ver < 0) return key;
+  return i18next.t(key, options);
+}

src/lib/i18n/index.svelte.ts

@@ -0,0 +1,54 @@
+/*
+ * Copyright 2025 - 2026 Zigflow authors <https://github.com/zigflow/studio/graphs/contributors>
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export type Locale = 'en' | 'en-GB';
+
+/**
+ * Map any string to a supported Locale.
+ * Exact match for 'en-GB'; everything else that starts with 'en' maps to 'en'.
+ * Unknown locales fall back to 'en'.
+ */
+export function resolveLocale(input: string | null | undefined): Locale {
+  if (input === 'en-GB') return 'en-GB';
+  return 'en';
+}
+
+/**
+ * Parse an Accept-Language header and return the best-matching supported
+ * Locale.  Respects q-values; first explicit en-GB match wins.
+ */
+export function parseAcceptLanguage(header: string | null): Locale {
+  if (!header) return 'en';
+
+  // Each part looks like "en-GB;q=0.9" or just "en".
+  const parts = header.split(',').map((s) => {
+    const [langRaw, qRaw] = s.trim().split(';q=');
+    return {
+      lang: (langRaw ?? '').trim(),
+      q: qRaw !== undefined ? parseFloat(qRaw) : 1.0,
+    };
+  });
+
+  // Sort by descending quality.
+  parts.sort((a, b) => b.q - a.q);
+
+  for (const { lang } of parts) {
+    if (lang === 'en-GB' || lang === 'en_GB') return 'en-GB';
+    if (lang.toLowerCase().startsWith('en')) return 'en';
+  }
+
+  return 'en';
+}

src/lib/i18n/locales.ts

@@ -0,0 +1 @@
+{}

src/lib/i18n/messages/en-GB.json

@@ -0,0 +1,63 @@
+{
+  "app": {
+    "name": "Zigflow Studio"
+  },
+  "workflows": {
+    "title": "Workflows",
+    "empty": "No workflow files found.",
+    "newPlaceholder": "workflow-name",
+    "newButton": "New workflow"
+  },
+  "editor": {
+    "saving": "Saving…",
+    "saved": "Saved",
+    "unsaved": "Unsaved changes",
+    "saveFailed": "Save failed",
+    "save": "Save",
+    "language": "Language",
+    "localeEn": "English (International)",
+    "localeEnGb": "English (British)",
+    "exportYaml": "Export YAML",
+    "noGraph": "No graph to display.",
+    "exportDialog": "YAML export"
+  },
+  "export": {
+    "title": "Exported YAML",
+    "close": "Close"
+  },
+  "inspector": {
+    "empty": "Select a node to inspect it.",
+    "id": "ID",
+    "kind": "Kind",
+    "detail": "Detail",
+    "condition": "Condition",
+    "structure": "Structure",
+    "branches": "Branches",
+    "removeBranch": "Remove branch {{label}}",
+    "addBranch": "+ Add branch",
+    "sections": "Sections",
+    "enterTryBody": "Enter try body",
+    "enterCatchBlock": "Enter catch block",
+    "addCatchBlock": "+ Add catch block",
+    "enterLoopBody": "Enter loop body",
+    "comingSoon": "Full editing UI coming soon.",
+    "moveUp": "↑ Move up",
+    "moveUpLabel": "Move task up",
+    "moveDown": "↓ Move down",
+    "moveDownLabel": "Move task down",
+    "delete": "Delete task"
+  },
+  "sidebar": {
+    "document": "Document",
+    "workflows": "Workflows",
+    "addWorkflow": "+ Add workflow",
+    "tasks": "Tasks",
+    "controlFlow": "Control flow"
+  },
+  "canvas": {
+    "ariaLabel": "Workflow canvas",
+    "tryBody": "try body",
+    "catchBlock": "catch block",
+    "loopBody": "body"
+  }
+}