feat: add internationalization (i18n) support (#164) (#1765)

* feat: add internationalization (i18n) support (#164)

Introduces full i18n support using next-intl with English (en) and German
(de) catalogs, persistent per-user locale preference, locale-aware
formatting, and a standardised server-side error code system so messages
can be translated client-side.

Highlights:
- next-intl integration with deep-merged English fallback for missing keys
- LanguageSwitcher component + setLocale GraphQL mutation
- bm_web_users.locale column + persisting/loading user preference
- ExposedError now carries stable code + meta; surfaced via GraphQL
  formatError and Koa error middleware (BAD_USER_INPUT messages pass
  through verbatim per the documented out-of-scope policy)
- Locale-aware date formatting via dynamic date-fns locale loading with
  promise dedupe and eager default-locale preload
- Localised react-select and @nateradebaugh/react-datetime widgets
- Comprehensive message extraction across components, pages, notifications
- New server/data/error-translation.js shared by REST + GraphQL helpers
- Added unit tests: error-translation, formatError, locale helpers,
  setLocale mutation, me.locale field
- Documentation: README + CONTRIBUTING updates covering localisation
  workflow, adding new locales, and ExposedError compatibility note

* fix(i18n): preserve password length detail via INVALID_PASSWORD_LENGTH

The Cypress login error test expects "Invalid password, minimum length 6
characters", but with i18n the client looks up the error code in the
translation catalog. The shared INVALID_PASSWORD code mapped to the
generic "Password is invalid", losing the actionable length detail.

Split into two codes so the message stays specific without baking the
magic number into translations:

- INVALID_PASSWORD: kept generic ("Password is invalid"), used for the
  unreachable type-mismatch case.
- INVALID_PASSWORD_LENGTH: parameterised via meta.minLength so the
  translated string ("Invalid password, minimum length {minLength}
  characters") matches the original UX.

Also exercises the meta pass-through end-to-end (Koa REST + GraphQL),
proving the translation pipeline works for parameterised messages.

Author: confuser

CONTRIBUTING.md

@@ -20,3 +20,77 @@ In order for us to help you please check that you've completed the following ste
 * Develop in a topic branch, not master (e.g. `feature/new-view`)
 * Write a convincing description of your PR and why we should land it
 * If you write JavaScript, make sure you follow https://standardjs.com/
+
+## Localisation
+
+The UI uses [`next-intl`](https://next-intl.dev/) for client-side translations. Translation catalogues live in [`messages/`](messages/) and the locale registry / negotiation logic lives in [`server/data/locales.js`](server/data/locales.js) (re-exported by [`utils/locale.js`](utils/locale.js) for client code).
+
+### Authoring rules
+
+* Always introduce new user-facing text via `useTranslations(...)` (or `t.rich(...)` when the message contains markup or interpolated React elements). Never hard-code English strings in components.
+* Group keys by feature area: `common.*`, `nav.*`, `forms.*`, `pages.<page>.*`, `errors.*`, `widgets.*`, `notifications.*`, `components.*`.
+* Use ICU MessageFormat for plurals/interpolation: `"Removed {count, plural, one {# item} other {# items}}"`.
+* Keep `messages/en.json` as the canonical source of truth. Every other locale must mirror its key structure exactly.
+
+### Adding a string
+
+1. Add the key + English copy to `messages/en.json`.
+2. Add a translation under the same key in every other locale file (`messages/de.json`, etc.). If a translation is unavailable at submission time, copy the English value as a placeholder so the key still resolves.
+3. Reference the key from a component:
+   ```js
+   import { useTranslations } from 'next-intl'
+
+   const t = useTranslations('pages.login')
+   return <h1>{t('title')}</h1>
+   ```
+
+### Adding a new locale
+
+1. Add the locale code to `SUPPORTED_LOCALES` in `server/data/locales.js`.
+2. Extend `LOCALE_CONFIG` in `utils/locale.js` with `label` (native name shown in the switcher), `htmlLang`, `openGraphLocale`, `dateFormat`, and `dateFnsLocale` (must match a [`date-fns` locale module](https://date-fns.org/v4.1.0/docs/I18n)).
+3. Add the locale entry to `dateFnsLocaleLoaders` in `utils/format-distance.js` so dynamic imports work.
+4. Create `messages/<locale>.json` with a 1:1 copy of `messages/en.json`, then translate.
+5. Run `npm run build` and `npm run test` to verify the locale loads and tests pass.
+
+The `LanguageSwitcher` component automatically picks up new locales from `SUPPORTED_LOCALES` and renders them using the `label` from `LOCALE_CONFIG`.
+
+### Server-side error messages
+
+Errors thrown from GraphQL resolvers, GraphQL directives, REST routes, and webhook handlers are translated client-side via stable error codes — **not** by translating the server's English text.
+
+* Always pass an error code as the second argument to `ExposedError`:
+  ```js
+  throw new ExposedError('Server not found', 'SERVER_NOT_FOUND')
+  ```
+* For dynamic content (e.g. plurals, names), pass a `meta` object as the third argument:
+  ```js
+  throw new ExposedError('This password isn\'t safe…', 'PASSWORD_COMPROMISED', { count: 5 })
+  ```
+* In Koa REST routes, call `ctx.throw(status, message, { code: 'STABLE_CODE', meta: {...} })` so the JSON body exposes `code` and `meta`. The `code` and `meta` properties are surfaced by the error middleware in [`server/app.js`](server/app.js).
+* Add a corresponding key to `messages/<locale>.json` under `errors.<CODE>` for every supported locale. Use ICU placeholders matching the `meta` keys.
+* The client UI (`components/ErrorMessages.js`/`utils/locale.js#translateGraphqlError` for GraphQL, `utils/locale.js#translateRestError` for REST) looks up the code and falls back to the server's message if no translation exists.
+* `BAD_USER_INPUT` errors (raised by `graphql-constraint-directive`) are intentionally **not** assigned an `appCode`, so the constraint message is shown verbatim. See the out-of-scope list below.
+
+> **Compatibility note**: `ExposedError` now defaults `code` to `'UNKNOWN'` (and `extensions.appCode` to `'UNKNOWN'`) when no second argument is supplied. Previously this field was `undefined`. Any downstream consumer that checks `if (!err.code)` should be updated to check for the literal string `'UNKNOWN'` instead. New call-sites must always pass an explicit, stable code.
+
+### Out-of-scope (explicitly NOT translated)
+
+The following surfaces are intentionally left in English to keep the scope manageable:
+
+* The setup/installer SPA under `server/setup/static/` (run-once flow).
+* CLI command output (`cli/commands/**`, `cli/utils/**`).
+* `graphql-constraint-directive` validation messages.
+* User-generated content (player names, ban reasons, appeal/report comments, custom roles, server names, document content).
+* Server logs and Pino output (`logger.*` calls).
+
+If you want to localise any of these, please open an issue first to discuss scope.
+
+### Manual verification
+
+Before submitting a PR that touches localisation:
+
+1. Toggle the language switcher in the top-right and confirm the page re-renders in the chosen language.
+2. Reload the page and confirm the choice persisted via the `bm_locale` cookie.
+3. If you're logged in, confirm `setLocale` ran and the preference survives a logout/login cycle.
+4. Check that `<html lang="…">` updates to match (DevTools → Elements panel).
+5. Trigger a known server error (e.g. submit invalid login) and verify the message renders in the active locale.

README.md

@@ -218,9 +218,22 @@ npm run test
 npm run cypress
 ```
 
+## Localisation
+
+The UI is localised with [`next-intl`](https://next-intl.dev/). Currently shipping languages: **English (`en`)** and **German (`de`)**.
+
+For details on adding a new language, translating new strings, or wiring up server-side error codes, see [`CONTRIBUTING.md`](CONTRIBUTING.md#localisation).
+
+Locale resolution order (highest priority first):
+
+1. Authenticated user's stored preference (`bm_web_users.locale`)
+2. `bm_locale` cookie (set by the in-app language switcher)
+3. `Accept-Language` HTTP header
+4. Fallback to `en`
+
 ## Contributing
 
-If you'd like to contribute, please fork the repository and use a feature branch. Pull requests are warmly welcome.
+If you'd like to contribute, please fork the repository and use a feature branch. Pull requests are warmly welcome. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for guidelines on translations, error codes, and other development conventions.
 
 ## Help / Bug / Feature Request
 

components/DateTimePicker.js

@@ -1,9 +1,16 @@
 import { forwardRef } from 'react'
 import Datetime from '@nateradebaugh/react-datetime'
+import { useLocale } from 'next-intl'
 import clsx from 'clsx'
+import { LOCALE_CONFIG, DEFAULT_LOCALE } from '../utils/locale'
+import { useDateFnsLocale } from '../utils/format-distance'
 
 // eslint-disable-next-line react/display-name
-const DateTimePicker = forwardRef(({ className = '', inputClassName = '', error = false, disabled = false, icon = null, iconPosition = 'left', ...rest }, ref) => {
+const DateTimePicker = forwardRef(({ className = '', inputClassName = '', error = false, disabled = false, icon = null, iconPosition = 'left', dateFormat, ...rest }, ref) => {
+  const locale = useLocale()
+  const dateFnsLocale = useDateFnsLocale()
+  const localeConfig = LOCALE_CONFIG[locale] || LOCALE_CONFIG[DEFAULT_LOCALE]
+  const resolvedDateFormat = dateFormat || localeConfig.dateFormat
   const inputClass = clsx(`
     flex-1
     appearance-none
@@ -46,7 +53,7 @@ const DateTimePicker = forwardRef(({ className = '', inputClassName = '', error
         <span className='rounded-l-3xl inline-flex items-center px-3 bg-primary-900 text-gray-400 text-lg'>
           {icon}
         </span>}
-      <Datetime ref={ref} dateFormat='dd/MM/yyyy' className={inputClass} {...rest} />
+      <Datetime ref={ref} dateFormat={resolvedDateFormat} locale={dateFnsLocale || undefined} className={inputClass} {...rest} />
     </div>
   )
 })

components/DefaultLayout.js

@@ -2,10 +2,12 @@ import { useEffect, useMemo } from 'react'
 import Head from 'next/head'
 import { NextSeo } from 'next-seo'
 import Favicon from 'react-favicon'
+import { useTranslations } from 'next-intl'
 import { MdLogin } from 'react-icons/md'
 import Footer from './Footer'
 import Nav from './Nav'
 import SessionNavProfile from './SessionNavProfile'
+import LanguageSwitcher from './LanguageSwitcher'
 import PlayerSelector from './admin/PlayerSelector'
 import { useApi, useUser } from '../utils'
 import { useRouter, withRouter } from 'next/router'
@@ -17,20 +19,29 @@ const query = `query unreadNotificationCount {
   unreadNotificationCount
 }`
 
-const LoggedOutNav = () => (
-  <div className='hidden md:flex gap-4'>
-    <Link href='/login' passHref>
-      <Button className='text-sm'>
-        <MdLogin className='mr-2' /> Login
-      </Button>
-    </Link>
-  </div>
-)
+const langButtonClassName = 'bg-primary-900 !rounded-lg p-2 transform transition duration-300 hover:scale-110 hover:bg-primary-900 w-12 h-12 items-center'
+
+const LoggedOutNav = () => {
+  const t = useTranslations('nav')
+
+  return (
+    <div className='hidden md:flex gap-4 items-center'>
+      <LanguageSwitcher buttonClassName={langButtonClassName} />
+      <Link href='/login' passHref>
+        <Button className='text-sm'>
+          <MdLogin className='mr-2' /> {t('login')}
+        </Button>
+      </Link>
+    </div>
+  )
+}
 
 function DefaultLayout ({ title = 'Default Title', children, description, loading }) {
   const { user } = useUser()
   const { data } = useApi({ query: user?.id ? query : null }, { refreshInterval: 10000, refreshWhenHidden: true })
   const router = useRouter()
+  const tForms = useTranslations('forms')
+  const tNav = useTranslations('nav')
 
   useEffect(() => {
     if (data) {
@@ -59,11 +70,11 @@ function DefaultLayout ({ title = 'Default Title', children, description, loadin
       <PlayerSelector
         multiple={false}
         onChange={(id) => id ? router.push(`/player/${id}`) : undefined}
-        placeholder='Search player'
+        placeholder={tForms('playerSelectorPlaceholder')}
       />
     </div>]
   const right = useMemo(() => user?.id ? [<SessionNavProfile key='session-nav-profile' user={user} unreadNotificationCount={data?.unreadNotificationCount} />] : [<LoggedOutNav key='nav-logged-out' />], [user, data])
-  const mobileItems = useMemo(() => !user?.id ? [{ name: 'Login', href: '/login' }, { name: 'Create Appeal', href: '/appeal' }] : [], [user])
+  const mobileItems = useMemo(() => !user?.id ? [{ name: tNav('login'), href: '/login' }, { name: tNav('createAppeal'), href: '/appeal' }] : [], [user, tNav])
 
   return (
     <>

components/ErrorMessages.js

@@ -1,6 +1,8 @@
 import { forwardRef } from 'react'
+import { useTranslations } from 'next-intl'
 import Message from './Message'
 import { uniqBy } from 'lodash-es'
+import { translateGraphqlError } from '../utils/locale'
 
 // eslint-disable-next-line react/display-name
 const ErrorMessages = forwardRef(({
@@ -10,44 +12,46 @@ const ErrorMessages = forwardRef(({
   parseError,
   errors
 }, ref) => {
+  const t = useTranslations()
+
   return (
     <>
       {error && (
         <Message ref={ref} error>
-          <Message.Header>Error</Message.Header>
+          <Message.Header>{t('errors.header')}</Message.Header>
           <Message.List data-cy='errors'>
-            <Message.Item>{error.message}</Message.Item>
+            <Message.Item>{translateGraphqlError(t, error)}</Message.Item>
           </Message.List>
         </Message>
       )}
       {fetchError && (
         <Message ref={ref} error>
-          <Message.Header>Fetch Error</Message.Header>
+          <Message.Header>{t('errors.fetchHeader')}</Message.Header>
           <Message.List>
             <Message.Item>{fetchError}</Message.Item>
           </Message.List>
         </Message>
       )}
       {httpError && (
         <Message ref={ref} error>
-          <Message.Header>HTTP error: {httpError.status}</Message.Header>
+          <Message.Header>{t('errors.httpHeader', { status: httpError.status })}</Message.Header>
           {httpError.statusText && <Message.List><Message.Item>{httpError.statusText}</Message.Item></Message.List>}
         </Message>
       )}
       {parseError && (
         <Message ref={ref} error>
-          <Message.Header>Parse Error</Message.Header>
+          <Message.Header>{t('errors.header')}</Message.Header>
           <Message.List>
             <Message.Item>{parseError}</Message.Item>
           </Message.List>
         </Message>
       )}
       {errors && (
         <Message ref={ref} error>
-          <Message.Header>Error</Message.Header>
+          <Message.Header>{t('errors.header')}</Message.Header>
           <Message.List data-cy='errors'>
-            {uniqBy(errors, 'message').map(({ message }, index) => (
-              <Message.Item key={index}>{message}</Message.Item>
+            {uniqBy(errors, 'message').map((err, index) => (
+              <Message.Item key={index}>{translateGraphqlError(t, err)}</Message.Item>
             ))}
           </Message.List>
         </Message>

components/Footer.js

@@ -1,5 +1,7 @@
 import Image from 'next/image'
+import { useTranslations } from 'next-intl'
 import { useApi } from '../utils'
+import LanguageSwitcher from './LanguageSwitcher'
 
 const query = `
   query settings {
@@ -10,26 +12,32 @@ const query = `
   }`
 
 export default function Footer () {
+  const t = useTranslations('footer')
+  const tCommon = useTranslations('common')
   const { data } = useApi({ query }, {
     revalidateIfStale: false,
     revalidateOnFocus: false,
     revalidateOnReconnect: false
   })
   const currentYear = new Date().getFullYear()
+  const fallbackName = `${t('powered')} ${tCommon('siteName')}`
 
   return (
     <footer className='text-gray-300 bg-primary-900'>
-      <div className='container px-5 py-8 mx-auto flex items-center sm:flex-row flex-col'>
+      <div className='container px-5 py-8 mx-auto flex items-center sm:flex-row flex-col gap-2'>
         <a className='flex title-font font-medium items-center md:justify-start justify-center'>
-          <Image src={(process.env.BASE_PATH || '') + '/images/banmanager-icon.png'} alt='Logo' width='35' height='35' />
-          <span className='ml-3 text-xl'>{data?.settings?.serverFooterName || 'Powered by BanManager'}</span>
+          <Image src={(process.env.BASE_PATH || '') + '/images/banmanager-icon.png'} alt={tCommon('siteName')} width='35' height='35' />
+          <span className='ml-3 text-xl'>{data?.settings?.serverFooterName || fallbackName}</span>
         </a>
         <p className='text-sm  sm:ml-4 sm:pl-4 sm:border-l-2 sm:border-gray-400 sm:py-2 sm:mt-0 mt-4'>
           &copy; {currentYear}
         </p>
         <p className='text-sm sm:pl-4 sm:py-2 sm:mt-0 mt-4'>
           {data?.settings?.additionalFooterText}
         </p>
+        <div className='sm:ml-auto'>
+          <LanguageSwitcher buttonClassName='!bg-primary-800 hover:!bg-primary-700 text-sm px-3 py-2' variant='inline' />
+        </div>
       </div>
     </footer>
   )