Scrumooth v2.1 Release: Multi-Language Support (i18n) - English, Deutsch, Español, Français, Italiano

[orbivort]

Tags: release i18n internationalization multi-language v2.1

---

Table of Contents

• Introduction
• What's New in v2.1.0
• Supported Languages
• How Multi-Language Support Works
• How to Use Multi-Language Support
• For Developers: Configuration & Code Examples
• i18n Quality Assurance & CI Integration
• Acknowledgments
• Feedback & Discussion
• References

---

Introduction

Scrumooth is a self-hosted Agile Scrum Lifecycle Management tool used by teams around the world, lightweight, easy-to-use, and faithful to the Scrum Guide. The entire interface — from dashboards and sprint boards to email notifications and error messages — was available only in English. For distributed teams and non-English-speaking organizations, this created an unnecessary barrier to adoption.

With v2.1, Scrumooth introduces full internationalization (i18n) across both the frontend and backend. Every user-facing string — UI labels, form validations, API error messages, email templates, and in-app notifications — is now translatable and delivered in the user's preferred language.

This is a significant milestone: it makes Scrumooth truly accessible to global teams, allowing each team member to work in their native language while collaborating on the same projects. A Product Owner in Berlin can navigate the backlog in Deutsch, while a Developer in Madrid views sprint tasks in Español - all within the same team workspace.

---

What's New in v2.1.0

As documented in the CHANGELOG under [2.1.0] - 2026-07-30:

Added

• i18n: add i18n multi language support
• i18n: support English, Deutsch, Español, Français, Italiano

This release delivers:

Capability	Description
5 production locales	English (en), Deutsch (de), Español (es), Français (fr), Italiano (it)
Full-stack i18n	Both frontend (React) and backend (Express.js) translate strings independently
Automatic language detection	Detects language from browser settings and cookies on first visit
Persistent language preference	User's language choice is saved to their profile and synced across devices
21 translation namespaces	16 frontend + 5 backend namespaces for organized, lazy-loaded translations
Type-safe translation keys	Frontend keys are validated at compile time via TypeScript augmentation
RTL readiness	Infrastructure for right-to-left languages is in place (dev testing via pseudo-RTL locale)
CI quality gates	Comprehensive i18n tooling suite (9 scripts) validates key parity, completeness, glossary consistency, and more

---

Supported Languages

Scrumooth v2.1.0 ships with five fully translated locales:

Code	Language	Native Name	BCP-47 Tag
en	English	English	en-US
de	German	Deutsch	de-DE
es	Spanish	Español	es-ES
fr	French	Français	fr-FR
it	Italian	Italiano	it-IT

English (en) is the default and fallback locale. If a translation key is missing in the user's selected language, the system gracefully falls back to English.

The architecture is designed to make adding new languages straightforward. A complete onboarding playbook for new locales is documented in the i18n Architecture guide.

---

How Multi-Language Support Works

Scrumooth's i18n implementation is full-stack, meaning translations happen independently on both the frontend and backend. This section explains the architecture in a way that's useful for both non-technical and technical readers.

High-Level Overview

┌─────────────────────────────────────────────────────────┐
│                    User's Browser                        │
│  ┌─────────────┐    ┌──────────────┐    ┌────────────┐  │
│  │ i18next     │    │ LanguageSwitcher│  │ Cookie     │  │
│  │ (React UI)  │    │ (User picks    │  │ scrumooth_ │  │
│  │             │◄──►│ language)      │──►│ locale     │  │
│  └──────┬──────┘    └──────────────┘    └─────┬──────┘  │
│         │                                       │        │
└─────────┼───────────────────────────────────────┼────────┘
          │ HTTP requests (with cookie +          │
          │ Accept-Language header)               │
          ▼                                       ▼
┌─────────────────────────────────────────────────────────┐
│                 Backend (Express.js)                     │
│  ┌──────────────┐  ┌─────────────┐  ┌────────────────┐  │
│  │ Locale       │  │ AsyncLocal  │  │ requestT()     │  │
│  │ Middleware   │──►│ Storage     │──►│ (Translates    │  │
│  │ (Resolves    │  │ (Per-request│  │ errors,        │  │
│  │  language)   │  │  context)   │  │ notifications, │  │
│  └──────────────┘  └─────────────┘  │ validation)    │  │
│                                      └────────────────┘  │
└─────────────────────────────────────────────────────────┘

For Non-Technical Readers

Here's what happens when you open Scrumooth:

1. First visit: Scrumooth checks your browser's language settings. If your browser is set to German, the interface automatically appears in Deutsch.
2. Manual switch: You can override the detected language at any time using the language switcher in the sidebar. Your choice is saved — both in your browser and (if you're logged in) on your user profile.
3. Consistent experience: Once you pick a language, everything adapts — the UI, error messages, email notifications, and form validation messages all appear in your chosen language.
4. Cross-device sync: If you're logged in, your language preference follows you across devices and browsers. Log in from a new browser, and Scrumooth remembers your language.

For Technical Readers

The i18n system is built on i18next v24+ and spans three packages: frontend, backend, and shared.

Frontend (React + Vite)

• i18next core with react-i18next for React integration
• i18next-http-backend loads namespace JSON files on demand from public/locales/{lng}/{ns}.json
• i18next-browser-languagedetector detects language from the scrumooth_locale cookie (fallback: navigator)
• intl-pluralrules polyfill for ICU pluralization
• 16 namespaces: common, auth, dashboard, backlog, sprint, daily-scrum, impediments, increments, sprint-review, retrospective, reports, team, settings, notifications, errors, validation
• Type-safe keys: Translation keys are validated at compile time via TypeScript module augmentation (i18n/types.ts)
• Zustand store (useI18nStore) holds the current locale, persists to localStorage, and writes the scrumooth_locale cookie so the backend can read it
• React Suspense handles loading states while namespaces fetch

Backend (Express.js)

• i18next.createInstance() creates a standalone backend instance (not the global singleton)
• All resources are bundled at build time (static imports with import ... with { type: 'json' })
• 5 namespaces: errors, validation, notifications, emails, retrospectives
• requestT (request translator): reads the locale from AsyncLocalStorage (per-request context) and calls i18nInstance.t(key, { lng: locale, ...options })
• Locale resolution middleware: determines the locale per request with this priority:
  1. Authenticated user's stored preference (req.user.locale)
  2. Accept-Language header (RFC 4647/9110 compliant, via resolve-accept-language)
  3. Default locale (en)
• Background jobs (emails, scheduled notifications) use i18nInstance.getFixedT(locale, ns) with an explicit locale from the user record, since they run outside the HTTP request lifecycle

Shared Package (@scrumooth/shared)

• SUPPORTED_LOCALES, DEFAULT_LOCALE, LOCALE_LABELS, LOCALE_BCP47_MAP
• normalizeLocale() — strips region subtags (de-AT -> de), falls back to en for unsupported bases
• isRTL(), getDirection() — RTL support infrastructure
• cookieConfig.ts — single source of truth for the scrumooth_locale cookie attributes (shared by frontend store, i18next detector, and backend middleware)

---

How to Use Multi-Language Support

Switching Language in the UI

1. Open the sidebar — Click the user avatar/menu in the bottom-left of the sidebar.
2. Find the language switcher — In the user dropdown menu, you'll see a globe icon followed by a language dropdown.
3. Select your language — Choose from the available languages. The interface updates instantly — no page reload required.

Sidebar > User Dropdown > [Globe Icon] Language: [English v]
                                        ├── English
                                        ├── Deutsch
                                        ├── Español
                                        ├── Français
                                        └── Italiano

Language Detection on First Visit

If you've never visited Scrumooth before (no scrumooth_locale cookie), the system checks your browser's language settings:

• If your browser is configured for German, Scrumooth starts in Deutsch.
• If your browser language isn't one of the five supported locales, it defaults to English.
• You can always override this by manually selecting a language.

Persistent Preferences

State	Where It's Stored	Scope
Not logged in	localStorage (scrumooth.locale) + cookie (scrumooth_locale)	Current browser only
Logged in	User profile (User.locale in database) + cookie	All devices — syncs on login

When you log in, Scrumooth syncs your server-stored language preference to your current browser. If you change languages while logged in, the preference is saved to your profile via a profile update API call, so it follows you to other devices and browsers.

What Gets Translated

Everything user-facing is translated:

• UI labels and buttons — navigation, forms, menus, toasts
• Dashboard and reports — chart labels, metrics, status names
• Form validation messages — both client-side and server-side
• API error messages — authentication errors, validation errors, not-found errors, database errors
• Email notifications — welcome emails, password reset emails, footer text
• In-app notifications — sprint events, task assignments, daily scrum reminders
• Workflow messages — state transition rejections, permission errors

---

For Developers: Configuration & Code Examples

This section provides code examples and configuration guidance for developers working with or extending Scrumooth's i18n system.

Frontend: i18n Initialization

The i18next instance is configured in packages/frontend/src/i18n/config.ts:

import i18n from 'i18next';
import HttpBackend from 'i18next-http-backend';
import LanguageDetector from 'i18next-browser-languagedetector';
import { initReactI18next } from 'react-i18next';
import { DEFAULT_LOCALE, LOCALE_COOKIE_NAME, LOCALE_COOKIE_PATH, LOCALE_COOKIE_SAME_SITE, SUPPORTED_LOCALES } from '@scrumooth/shared';

export const i18nInstance = i18n
  .use(HttpBackend)
  .use(LanguageDetector)
  .use(initReactI18next);

export function initI18n(): Promise<TFunction> {
  const localeBasePath = (import.meta.env.VITE_BASE_PATH ?? '/').replace(/\/+$/, '');
  return i18nInstance.init({
    backend: {
      loadPath: `${localeBasePath}/locales/{{lng}}/{{ns}}.json`,
    },
    detection: {
      order: ['cookie', 'navigator'],
      lookupCookie: LOCALE_COOKIE_NAME,
      caches: ['cookie'],
    },
    fallbackLng: DEFAULT_LOCALE,
    supportedLngs: [...SUPPORTED_LOCALES],
    load: 'currentOnly',
    ns: [
      'common', 'auth', 'dashboard', 'backlog', 'sprint',
      'daily-scrum', 'impediments', 'increments', 'sprint-review',
      'retrospective', 'reports', 'team', 'settings',
      'notifications', 'errors', 'validation',
    ],
    defaultNS: 'common',
    interpolation: { escapeValue: false },
    react: { useSuspense: true },
    returnNull: false,
    returnEmptyString: false,
  });
}

The initialization is called at app startup in App.tsx:

import { I18nProvider } from './i18n/I18nProvider';
import { initI18n } from './i18n/config';

void initI18n();

return (
  <ErrorBoundary>
    <I18nProvider>
      <QueryClientProvider client={queryClient}>
        {/* App content */}
      </QueryClientProvider>
    </I18nProvider>
  </ErrorBoundary>
);

Frontend: Using Translations in Components

Use the useTranslation hook from react-i18next. Keys are type-safe — the TypeScript compiler validates them against the English JSON resources.

import { useTranslation } from 'react-i18next';

export const LoginPage: React.FC = () => {
  // Pass the namespace as an argument; defaults to 'common'
  const { t } = useTranslation('auth');

  return (
    <div className={styles['auth-page']}>
      <h1>{t('welcomeBack')}</h1>
      <p>{t('login.signInTo', { app: 'Scrumooth' })}</p>

      <label htmlFor="email">{t('email')}</label>
      <input placeholder={t('placeholder.email')} />

      <label htmlFor="firstName">{t('firstName')}</label>
      <input placeholder={t('login.placeholder.firstName')} />
    </div>
  );
};

Key features:

• Namespace selection: useTranslation('auth') loads the auth namespace
• Interpolation: t('login.signInTo', { app: 'Scrumooth' }) renders "Sign in to {{app}}" -> "Sign in to Scrumooth"
• Dotted keys: Nested JSON objects are accessed via dot notation (login.placeholder.firstName)
• Pluralization: i18next automatically selects _one / _other suffixes based on count

Frontend: The Language Switcher Component

The LanguageSwitcher component (packages/frontend/src/components/common/LanguageSwitcher/) is mounted in the sidebar user dropdown:

import { useTranslation } from 'react-i18next';
import { useI18nStore } from '@/i18n/useI18nStore';
import { useAuthStore } from '@/contexts/AuthContext';
import { LOCALE_LABELS, type Locale } from '@scrumooth/shared';

export const LanguageSwitcher: React.FC = () => {
  const { t } = useTranslation();
  const { locale, setLocale } = useI18nStore();
  const { user, updateProfile } = useAuthStore();

  const handleChange = async (newLocale: Locale) => {
    setLocale(newLocale); // Updates Zustand store + cookie
    if (user) {
      // Persist to server so it syncs across devices
      await updateProfile({
        firstName: user.firstName,
        lastName: user.lastName,
        locale: newLocale,
      });
    }
  };

  return (
    <select
      value={locale}
      onChange={(e) => handleChange(e.target.value as Locale)}
      aria-label={t('selectLanguage')}
    >
      {Object.entries(LOCALE_LABELS).map(([code, label]) => (
        <option key={code} value={code}>{label}</option>
      ))}
    </select>
  );
};

Frontend: The Zustand i18n Store

The useI18nStore (packages/frontend/src/i18n/useI18nStore.ts) manages locale state:

import { create } from 'zustand';
import { persist } from 'zustand/middleware';
import { DEFAULT_LOCALE, getLocaleCookieOptions, type Locale } from '@scrumooth/shared';

interface I18nState {
  locale: Locale;
  setLocale: (locale: Locale) => void;
}

export const useI18nStore = create<I18nState>()(
  persist(
    (set) => ({
      locale: DEFAULT_LOCALE,
      setLocale: (locale) => {
        set({ locale });
        // Write cookie so backend locale middleware can read it
        const opts = getLocaleCookieOptions('browser');
        const expires = new Date(Date.now() + opts.maxAge).toUTCString();
        document.cookie = `${opts.name}=${locale}; Expires=${expires}; Path=${opts.path}; SameSite=${opts.sameSite}`;
      },
    }),
    {
      name: 'scrumooth.locale',
      partialize: (state) => ({ locale: state.locale }),
    }
  )
);

Backend: Request-Scoped Translation

The backend uses requestT to translate strings within the HTTP request lifecycle. The locale is resolved by middleware and propagated via AsyncLocalStorage:

// packages/backend/src/i18n/requestT.ts
import { i18nInstance } from './config';
import { getRequestLocale, DEFAULT_LOCALE } from '../utils/requestContext';

export function t(key: string, options?: Record<string, unknown>): string {
  const locale = getRequestLocale();
  return i18nInstance.t(key, { lng: locale, ...options });
}

Usage in error-handling middleware:

import { t } from '../i18n/requestT';

// JWT errors
throw new UnauthorizedError(t('errors:invalidToken'));

// Prisma unique constraint violation
t('errors:fieldAlreadyExists', { field: 'email' });

// Pluralized notification
t('notifications:remindersSent', { count: successCount });
// -> "1 reminder sent" or "3 reminders sent"

Backend: Locale Resolution Middleware

The localeResolver middleware determines the language for each request:

// packages/backend/src/middleware/locale.middleware.ts
export const localeResolver: RequestHandler = (req, res, next) => {
  let locale: string;

  // Priority 1: Authenticated user's stored preference
  if (req.user?.locale && SUPPORTED_LOCALES.includes(req.user.locale)) {
    locale = req.user.locale;
  }
  // Priority 2: Accept-Language header (RFC 4647 compliant)
  else {
    const resolved = resolveAcceptLanguage(
      req.headers['accept-language'] ?? '',
      BCP47_LOCALES,
      BCP47_DEFAULT
    );
    locale = normalizeLocale(resolved);
  }

  // Priority 3: Default to 'en' (handled by normalizeLocale fallback)
  res.cookie(LOCALE_COOKIE_NAME, locale, getLocaleCookieOptions('server'));
  updateRequestContext({ locale });
  next();
};

Backend: Background Jobs & Emails

For code running outside the request lifecycle (emails, scheduled notifications), use getFixedT with an explicit locale:

import { i18nInstance } from '../i18n/config';

// Email template
const t = i18nInstance.getFixedT(user.locale, 'emails');
const subject = t('welcome.subject');
const greeting = t('common.greeting', { name: user.firstName });

// Persistent notification
const t = i18nInstance.getFixedT(user.locale, 'notifications');
const title = t(titleKey, titleParams);
const message = t(messageKey, messageParams);

Translation File Structure

Frontend locale files live in packages/frontend/public/locales/:

public/locales/
├── en/
│   ├── common.json       # Shared UI strings
│   ├── auth.json         # Login/register pages
│   ├── dashboard.json    # Dashboard widgets
│   ├── backlog.json      # Product backlog
│   ├── sprint.json       # Sprint board & planning
│   ├── ...
│   └── validation.json   # Form validation messages
├── de/
│   ├── common.json
│   ├── ...
├── es/
├── fr/
└── it/

Backend locale files live in packages/backend/src/locales/:

src/locales/
├── en/
│   ├── errors.json           # API error messages
│   ├── validation.json       # Server-side validation
│   ├── notifications.json    # In-app notification text
│   ├── emails.json           # Email subjects & bodies
│   └── retrospectives.json   # Retrospective labels
├── de/
├── es/
├── fr/
└── it/

Example translation JSON (en/common.json):

{
  "language": "Language",
  "selectLanguage": "Select language",
  "welcomeBack": "Welcome back",
  "loading": "Loading...",
  "attendeesSection": {
    "attendanceCount": "{{count}} attendees",
    "attendanceCount_one": "{{count}} attendee"
  }
}

Adding a New Language

To add a new locale (e.g., Portuguese — pt):

1. Create locale directories:

   • packages/frontend/public/locales/pt/ — copy all 16 namespace JSON files from en/
   • packages/backend/src/locales/pt/ — copy all 5 namespace JSON files from en/

2. Register the locale in packages/shared/src/constants/index.ts:

   export const SUPPORTED_LOCALES = ['en', 'de', 'fr', 'it', 'es', 'pt'] as const;
   export const LOCALE_LABELS: Record<Locale, string> = {
     en: 'English', de: 'Deutsch', fr: 'Français',
     it: 'Italiano', es: 'Español', pt: 'Português',
   };

3. Translate all values in the JSON files (replace English strings with Portuguese translations). Mark incomplete translations with "__pending__" — the pendingGuard post-processor will display a localized fallback in production.

4. Validate:

   pnpm run i18n:check         # Validate key parity
   pnpm run i18n:completeness  # Check translation coverage

5. Add BCP-47 mapping in LOCALE_BCP47_MAP:

   pt: 'pt-BR',

A complete onboarding playbook with a worked example (using pt) is available in the i18n Architecture document.

---

i18n Quality Assurance & CI Integration

Scrumooth includes a comprehensive suite of i18n tooling to maintain translation quality. These scripts run in CI and as pre-commit hooks:

Command	Purpose
pnpm run i18n:check	Validates key parity, interpolation placeholder matching, and no empty values across all locales
pnpm run i18n:check:strict	Same as above, plus fails on any __pending__ sentinel values
pnpm run i18n:extract	Heuristic scanner — reports potential hardcoded translatable strings in source code
pnpm run i18n:extract:check	AST-based extraction — verifies all t() keys used in code exist in locale JSON
pnpm run i18n:completeness	Generates a per-locale/per-namespace coverage report
pnpm run i18n:completeness:strict	Same as above, exits with error if any locale is below 80% coverage
pnpm run i18n:glossary	Enforces consistent Scrum terminology across translations (e.g., "Sprint" must be translated consistently)
pnpm run i18n:pseudo	Generates a pseudo-localized locale for testing UI layout resilience to longer/accented strings
pnpm run i18n:sort	Alphabetically sorts JSON keys in all locale files (runs automatically via lint-staged on commit)

Pre-commit hook: Any committed locale JSON file automatically triggers i18n:sort and i18n:check via lint-staged, ensuring formatting and key parity are maintained.

Release workflow: The prepare-release.yml GitHub Action runs i18n:check:strict before creating a release PR, blocking releases with incomplete translations.

---

Acknowledgments

The multi-language support feature was developed by the Orbivort team as a major milestone in making Scrumooth accessible to global teams.

We acknowledge:

• The i18next team for their excellent internationalization framework that powers both the frontend and backend translation systems
• The react-i18next community for React-specific i18n integration
• The resolve-accept-language library for RFC 4647/9110 compliant language negotiation
• All community members who provided feedback, tested early builds, and reported issues during development

Scrumooth is an open-source project licensed under the Apache License 2.0. We welcome contributions — whether it's adding a new language, improving existing translations, or enhancing the i18n infrastructure. If you'd like to contribute a translation for a language not yet supported, please open a discussion or issue in the GitHub repository.

---

Feedback & Discussion

We want to hear from you! This release is a major step toward making Scrumooth a truly global platform, and your feedback shapes what comes next.

Share Your Experience

• How is multi-language support working for your team? Let us know which languages your team uses and whether the translations feel natural.
• Found a translation issue? Please report it in GitHub Issues with the label i18n. Include the locale, the screen/feature, and the expected vs. actual translation.
• Want a language that's not yet supported? Vote or request in the comments below. Languages with high community demand will be prioritized.

Planned Future Improvements

• Additional languages based on community demand
• Right-to-left (RTL) language support (infrastructure is in place; Phase 5 of the i18n roadmap)
• Community translation portal for crowdsourced contributions
• Glossary expansion for domain-specific Scrum terminology

Questions?

Drop a comment below or start a new discussion in the Announcements category. We respond to all questions.

---

References

• CHANGELOG.md — v2.1.0 Release Notes
• i18n Architecture Documentation
• Scrumooth GitHub Repository
• i18next Documentation
• react-i18next Documentation
• Full Changelog: v2.0.5...v2.1.0

---

Scrumooth is a self-hosted Agile Scrum Lifecycle Management System. Copyright 2026 Orbivort. Licensed under the Apache License, Version 2.0.