feat: copy management — react-i18next adopted, Settings migrated (goal 0032) (#19)

Owner-observed 40/72 .tsx files carrying inline hardcoded copy with no
i18n library. Research settled on plain i18n over a headless CMS (every
git-native CMS candidate needs a hosted OAuth intermediary or a local
daemon, disqualified by SPEC §1.1): react-i18next v17.0.11 + i18next
v26.3.6, namespace-per-bounded-context JSON under
frontend/src/locales/en/ mirroring frontend/src's own folders, init in
app/i18n.ts wired from main.tsx.

Migrated SettingsView.tsx as the proof-of-pattern slice (views.json's
settings namespace + common.json's shared verbs); existing
e2e/settings.spec.ts assertions pass unchanged since translated text
matches the original English exactly. Added app/i18n.test.ts (init
loads, t() resolves keys, interpolation).

The remaining ~39 files are tracked as four Standing tech-debt entries
in BACKLOG.md (app/, composition/, configure/, views/ minus Settings),
each independently DoR/DoD-shaped. eslint-plugin-i18next evaluated and
deliberately deferred — its no-literal-string rule would fail the lint
gate across every still-unmigrated file rather than guard new code
alone.

Goal 0032 left OPEN (not archived) per its own Plan step 3 — the
migration is intentionally staged, not silently dropped.


Claude-Session: https://claude.ai/code/session_018pkViCNAuZp2vBv2K9AbUh

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

Author: alicoding

frontend/package-lock.json

@@ -23,11 +23,13 @@
     "cronstrue": "^3.24.0",
     "elkjs": "^0.12.0",
     "genson-js": "^0.0.8",
+    "i18next": "^26.3.6",
     "papaparse": "^5.5.4",
     "randexp": "^0.5.3",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "react-dropzone": "^20.1.0",
+    "react-i18next": "^17.0.11",
     "react-is": "^19.2.8",
     "react-querybuilder": "^8.22.4",
     "recharts": "^3.10.1",

frontend/package.json

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest'
+import i18n from './i18n'
+
+// docs/goals/0032-copy-management.md's proof-of-pattern slice: confirms
+// the init actually wires resources up (a config typo or a missing
+// namespace in the `ns` list would otherwise only surface as a blank
+// string live, in whichever component happened to call t() first).
+describe('i18n init', () => {
+  it('initializes synchronously with English as the active language', () => {
+    expect(i18n.isInitialized).toBe(true)
+    expect(i18n.language).toBe('en')
+  })
+
+  it('resolves a known key from the views namespace (Settings slice)', () => {
+    expect(i18n.t('settings.title', { ns: 'views' })).toBe('Settings')
+  })
+
+  it('resolves a known key from the common namespace via the ns-prefixed form', () => {
+    expect(i18n.t('common:actions.change')).toBe('Change')
+  })
+
+  it('interpolates variables into a templated key', () => {
+    expect(i18n.t('settings.updates.updateAvailable', { ns: 'views', version: '1.2.3' })).toBe('Update available: v1.2.3')
+  })
+
+  it('falls back to the key itself for an unknown key, never throwing', () => {
+    expect(() => i18n.t('settings.doesNotExist', { ns: 'views' })).not.toThrow()
+  })
+})

frontend/src/app/i18n.test.ts

@@ -0,0 +1,48 @@
+import i18n from 'i18next'
+import { initReactI18next } from 'react-i18next'
+import common from '../locales/en/common.json'
+import app from '../locales/en/app.json'
+import composition from '../locales/en/composition.json'
+import configure from '../locales/en/configure.json'
+import views from '../locales/en/views.json'
+
+// docs/goals/0032-copy-management.md's locked research verdict:
+// react-i18next + i18next, namespace-per-bounded-context JSON --
+// mirroring frontend/src's own app/composition/configure/shared/views
+// folders -- chosen over every git-native headless-CMS candidate
+// (Decap/Sveltia/Keystatic/Tina), all of which need either a hosted
+// OAuth intermediary or a locally-running backend daemon, disqualified
+// by SPEC §1.1's no-hosted-service/no-second-daemon constraint. This
+// is copy-CENTRALIZATION (key -> string JSON, no authoring UI, no
+// CMS product), not localization -- there is no language switcher and
+// no plan for one yet; English is the only shipped locale. Resources
+// are imported statically and bundled at build time (Vite's own
+// resolveJsonModule support), never fetched at runtime, so this adds
+// zero network calls and zero server, matching Mill's own hard
+// constraints.
+//
+// Initialized once here and imported for its side effect from
+// app/main.tsx, before the first render -- react-i18next's
+// useTranslation() hook reads the already-initialized global i18next
+// instance from any bounded-context folder without importing this
+// module directly (app/ is the only folder allowed to import this,
+// per .claude/rules/frontend.md's dependency-cruiser boundaries; every
+// other folder just calls useTranslation() from the 'react-i18next'
+// package).
+void i18n.use(initReactI18next).init({
+  resources: {
+    en: { common, app, composition, configure, views },
+  },
+  lng: 'en',
+  fallbackLng: 'en',
+  defaultNS: 'common',
+  ns: ['common', 'app', 'composition', 'configure', 'views'],
+  interpolation: {
+    // React already escapes interpolated values when rendering JSX --
+    // i18next's own default (HTML-escaping) would double-escape them.
+    escapeValue: false,
+  },
+  returnNull: false,
+})
+
+export default i18n

frontend/src/app/i18n.ts

@@ -1,5 +1,6 @@
 import React from 'react'
 import ReactDOM from 'react-dom/client'
+import './i18n'
 import './index.css'
 import '@primer/primitives/dist/css/primitives.css'
 import '@primer/primitives/dist/css/functional/themes/light.css'

frontend/src/app/main.tsx

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

frontend/src/locales/en/app.json

@@ -0,0 +1,6 @@
+{
+  "actions": {
+    "change": "Change",
+    "clear": "Clear"
+  }
+}

frontend/src/locales/en/common.json

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

frontend/src/locales/en/composition.json

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

frontend/src/locales/en/configure.json

@@ -0,0 +1,56 @@
+{
+  "settings": {
+    "title": "Settings",
+    "subtitle": "App-level preferences -- not workflow or Configure-authored data (that lives in Composition/Configure), a UI preference persisted locally to this machine.",
+    "loadError": "Couldn't load some settings -- the app may need a restart.",
+    "sections": {
+      "appearance": "Appearance",
+      "general": "General",
+      "keyboardShortcuts": "Keyboard Shortcuts",
+      "globalHotkey": "Global hotkey",
+      "mcpAccess": "MCP access",
+      "notifications": "Notifications",
+      "updates": "Updates"
+    },
+    "appearance": {
+      "themeLabel": "Color theme",
+      "lightLabel": "Light theme",
+      "darkLabel": "Dark theme",
+      "systemLabel": "Match system theme"
+    },
+    "general": {
+      "launchAtLoginLabel": "Launch Mill at login",
+      "launchAtLoginCaption": "Starts Mill automatically when you log in, same as Raycast/Alfred (docs/SPEC.md §3.7).",
+      "errorDevBinary": "Not available in this dev build -- only a built .app bundle can be a login item.",
+      "errorServerMode": "Not available in server mode -- there is no login-item concept without a desktop app to register."
+    },
+    "keyboardShortcuts": {
+      "description": "Every in-window command Mill dispatches (docs/goals/0016-keymap-system.md) -- rebind by clicking a combo and pressing a new one, the same recorder used for a workflow's own trigger hotkey below."
+    },
+    "globalHotkey": {
+      "description": "Opens Mill's Quick Panel from anywhere, like Raycast's ⌥Space or Alfred's own shortcut -- search and run a workflow, or jump into Mill itself, without leaving what you were doing. Press again to dismiss it. Distinct from a specific workflow's own trigger hotkey (set per-workflow on its canvas).",
+      "recording": "Press a combo… (Esc to cancel)",
+      "setShortcut": "Set shortcut",
+      "reservedError": "{{combo}} is reserved by macOS ({{reason}}) — pick another combo",
+      "openAccessibilitySettings": "Open Accessibility Settings"
+    },
+    "mcp": {
+      "allowImportLabel": "Allow MCP clients to import data",
+      "allowImportCaption": "Off by default (docs/adr/0017): when on, an external MCP client connected to Mill's local MCP server can create workflows, integrations, lists, and MCP-server entries via the import tools -- reading/exporting is always allowed and never includes secrets. Applies immediately, no restart.",
+      "askBeforeImportLabel": "Ask me before each MCP import",
+      "askBeforeImportCaption": "On by default (docs/adr/0022): each import parks until you approve it in Mill's window (or times out after 2 minutes, which denies it). Turning this off lets an enabled MCP client import without a per-write click -- enabling writes shouldn't silently mean unattended writes."
+    },
+    "notifications": {
+      "description": "A parked guardrail ask or MCP write notifies you and shows a floating approval prompt (docs/adr/0032, docs/goals/0023) once you're away -- not merely unfocused, but idle past the threshold below, or genuinely unfocused. A present, actively-using-Mill window is never double-noised.",
+      "awayAfterLabel": "Away after (seconds)",
+      "awayAfterCaption": "How long the Mac must sit idle (no keyboard/mouse/trackpad input) while Mill is focused before you're treated as away -- 300s (5 minutes) by default, matching Teams' own away-status default. Losing focus entirely always counts as away regardless of this number.",
+      "alertPermissionNote": "For the notification to alert instead of only appearing quietly in Notification Center, allow it in System Settings → Notifications → Mill → Alerts (docs/goals/0023 item 3) -- Mill requests notification permission on first launch, but macOS still defaults new apps to Banners, which auto-dismiss."
+    },
+    "updates": {
+      "checkButton": "Check for updates",
+      "checking": "Checking…",
+      "updateAvailable": "Update available: v{{version}}",
+      "upToDate": "You're on the latest version."
+    }
+  }
+}