Version: 0.9.1 Date: February 3, 2026 Status: Implementation Plan Tasks: TODO.md #121, #122, #123 (Phase 18)

This document provides a comprehensive implementation plan for completing internationalization (i18n) and accessibility (a11y) features in nself-chat to production-ready status. The plan addresses:

• Task 121: Complete i18n translation coverage
• Task 122: Ensure WCAG AA accessibility compliance
• Task 123: Add accessibility tests to CI

Spanish (es) - Missing Files:

src/locales/es/
├── common.json    [EXISTS]
├── chat.json      [EXISTS]
├── settings.json  [EXISTS]
├── admin.json     [NEEDED] - ~160 keys
├── auth.json      [NEEDED] - ~120 keys
└── errors.json    [NEEDED] - ~100 keys

French (fr) - Missing Files:

src/locales/fr/
├── common.json    [EXISTS]
├── chat.json      [EXISTS]
├── settings.json  [EXISTS]
├── admin.json     [NEEDED] - ~160 keys
├── auth.json      [NEEDED] - ~120 keys
└── errors.json    [NEEDED] - ~100 keys

Arabic (ar) - Missing Files + RTL Testing:

src/locales/ar/
├── common.json    [EXISTS]
├── chat.json      [EXISTS]
├── settings.json  [NEEDED] - ~140 keys
├── admin.json     [NEEDED] - ~160 keys
├── auth.json      [NEEDED] - ~120 keys
└── errors.json    [NEEDED] - ~100 keys

Chinese, Portuguese, Russian - Similar Pattern:

• Each needs: settings.json, admin.json, auth.json, errors.json

1. Automated String Extraction

   # Create extraction script
   # Scans all .tsx/.ts files for hardcoded strings
   # Outputs report of strings needing extraction

2. Component Audit Checklist

   • All user-facing text uses t() function
   • Placeholder text is translated
   • Error messages use translation keys
   • Date/time displays use locale formatters
   • Numbers use locale formatters
   • Button labels are translated
   • Form labels and validation messages translated
   • Toast/notification messages translated
   • Modal titles and content translated
   • Empty states and loading states translated

3. Areas Requiring Special Attention src/components/setup/ # 9-step wizard src/components/chat/ # Core messaging UI src/components/admin/ # Admin dashboard src/components/settings/ # Settings pages src/components/auth/ # Auth flows src/app/ # All pages

Implementation Strategy:

// src/lib/i18n/translation-validator.ts

export interface TranslationValidationResult {
  locale: string
  namespace: string
  missingKeys: string[]
  extraKeys: string[]
  totalKeys: number
  coverage: number
}

export function validateTranslations(
  baseLocale: string = 'en',
  targetLocale: string
): TranslationValidationResult[]

export function generateMissingKeysReport(): void

CI Integration:

# .github/workflows/i18n-check.yml
- name: Check translation coverage
  run: pnpm run i18n:validate
  # Fails if any language < 100% coverage

1. Contributor Workflow

   1. Fork repository
   2. Copy English file as template
   3. Translate keys
   4. Run validation: pnpm i18n:validate
   5. Submit PR
   6. Native speaker review
   7. Merge
   

2. Translation Key Guidelines

   • Use dot notation for nesting: messages.new.title
   • Use descriptive names: button.sendMessage not btn1
   • Group by feature: chat.reactions.add
   • Include context in key name when needed: delete.confirmTitle

3. Quality Standards

   • Native speaker review required
   • Context-aware translations
   • Consistent terminology (create glossary)
   • Proper pluralization
   • Natural language flow

• Basic RTL support exists in src/lib/i18n/rtl.ts
• Arabic locale configured with direction: 'rtl'
• CSS logical properties partially implemented

1. CSS Updates for RTL

   /* src/styles/rtl.css - New file */
   
   [dir='rtl'] {
     /* Sidebar positioning */
     .sidebar {
       right: 0;
       left: auto;
     }
   
     /* Message alignment */
     .message-own {
       margin-left: 0;
       margin-right: auto;
     }
   
     /* Icon flipping */
     .icon-arrow,
     .icon-chevron {
       transform: scaleX(-1);
     }
   }

2. Component Updates

   • Audit all components for directional assumptions
   • Replace left/right with start/end in Tailwind
   • Use CSS logical properties: margin-inline-start

3. Testing RTL

   • Add E2E tests for Arabic layout
   • Verify sidebar positioning
   • Verify message alignment
   • Verify icon directions
   • Verify text alignment

• formatDate() with locale support
• formatTime() with locale support
• formatRelativeTime() for "2 hours ago"
• formatMessageTime() smart formatting
• Calendar week start (Sunday vs Monday)
• 12-hour vs 24-hour preference per locale
• Date input components locale-aware

• formatNumber() with locale separators
• formatCurrency() with locale symbols
• formatBytes() for file sizes
• formatPercentage() for analytics
• Ordinal numbers (1st, 2nd, 3rd)
• Number input components locale-aware

{
  "messages_zero": "No messages",
  "messages_one": "1 message",
  "messages_other": "{{count}} messages"
}

1. Audit Theme Presets

   // Script to audit all 25+ theme presets
   // src/scripts/audit-contrast.ts
   
   import { themePresets } from '@/lib/theme-presets'
   import { getContrastRatio } from '@/lib/a11y/color-contrast'
   
   function auditThemes(): ContrastReport[]

2. Fix Non-Compliant Themes

   • Adjust text colors where contrast < 4.5:1
   • Adjust UI component colors where contrast < 3:1
   • Document any exceptions with justification

3. Contrast Checking Utilities

   • Already implemented in src/lib/a11y/color-contrast.ts
   • Includes: meetsWCAG_AA(), meetsWCAG_AAA(), adjustColorForContrast()

1. Skip Links

   // src/components/accessibility/skip-links.tsx
   
   export function SkipLinks() {
     return (
       <div className="skip-links">
         <a href="#main-content" className="skip-link">
           Skip to main content
         </a>
         <a href="#channel-list" className="skip-link">
           Skip to channels
         </a>
         <a href="#message-input" className="skip-link">
           Skip to message input
         </a>
       </div>
     )
   }

2. Keyboard Shortcuts Documentation

   • Already have settings page at /settings/accessibility
   • Need to ensure all shortcuts are documented
   • Need to allow shortcut customization

3. Focus Order Audit

   • Audit all pages for logical tab order
   • Fix any focus order issues
   • Ensure modals trap focus correctly

1. Landmark Roles

   // Ensure proper landmarks in layout
   <header role="banner">...</header>
   <nav role="navigation">...</nav>
   <main role="main" id="main-content">...</main>
   <aside role="complementary">...</aside>
   <footer role="contentinfo">...</footer>

2. ARIA Labels Audit

   • Icon-only buttons must have aria-label
   • Form inputs must have associated labels
   • Interactive elements need accessible names
   • Status indicators need text alternatives

3. Live Regions for Dynamic Content

   // New messages announcement
   <div aria-live="polite" aria-atomic="false">
     {/* Announce new messages */}
   </div>
   
   // Error announcements
   <div aria-live="assertive" aria-atomic="true">
     {/* Announce errors */}
   </div>

Already well-implemented in:

• src/lib/accessibility/use-focus-management.ts
• src/contexts/accessibility-context.tsx
• src/styles/accessibility.css

1. Focus Visible Styling

   /* Already in accessibility.css - verify consistency */
   :focus-visible {
     outline: 2px solid var(--ring);
     outline-offset: 2px;
   }

2. Focus Restoration

   • After modal closes, return focus to trigger
   • After navigation, focus page heading
   • After form submission, focus feedback message

1. Form Validation Errors

   // Error must be:
   // 1. Visually indicated (not just color)
   // 2. Programmatically associated with field
   // 3. Announced to screen readers
   
   ;<input id="email" aria-invalid={!!error} aria-describedby={error ? 'email-error' : undefined} />
   {
     error && (
       <div id="email-error" role="alert" className="error-message">
         <ErrorIcon aria-hidden="true" />
         <span>{error}</span>
       </div>
     )
   }

2. Status Messages

   // Success messages
   <div role="status" aria-live="polite">
     Settings saved successfully
   </div>
   
   // Error messages
   <div role="alert" aria-live="assertive">
     Failed to send message. Please try again.
   </div>

• Headings in proper hierarchy (h1 -> h2 -> h3)
• Lists use <ul>, <ol>, <dl>
• Tables have proper headers and scope
• Forms have proper labels
• Buttons vs links used appropriately
• Regions have proper landmarks

# Already installed
@axe-core/playwright: ^4.10.2

# Need to add
pnpm add -D jest-axe @types/jest-axe eslint-plugin-jsx-a11y

// src/test/setup-a11y.ts
import { toHaveNoViolations } from 'jest-axe'

expect.extend(toHaveNoViolations)

// src/components/ui/__tests__/button.a11y.test.tsx
import { render } from '@testing-library/react';
import { axe } from 'jest-axe';
import { Button } from '../button';

describe('Button Accessibility', () => {
  it('should have no accessibility violations', async () => {
    const { container } = render(<Button>Click me</Button>);
    const results = await axe(container);
    expect(results).toHaveNoViolations();
  });

  it('should have accessible name when icon-only', async () => {
    const { container } = render(
      <Button aria-label="Settings">
        <SettingsIcon aria-hidden="true" />
      </Button>
    );
    const results = await axe(container);
    expect(results).toHaveNoViolations();
  });
});

// e2e/accessibility.spec.ts
import { test, expect } from '@playwright/test'
import AxeBuilder from '@axe-core/playwright'

test.describe('Accessibility', () => {
  test('home page should have no accessibility violations', async ({ page }) => {
    await page.goto('/')

    const accessibilityScanResults = await new AxeBuilder({ page })
      .withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'])
      .analyze()

    expect(accessibilityScanResults.violations).toEqual([])
  })

  test('chat page should have no accessibility violations', async ({ page }) => {
    await page.goto('/chat')
    await page.waitForSelector('[data-testid="message-list"]')

    const accessibilityScanResults = await new AxeBuilder({ page })
      .withTags(['wcag2a', 'wcag2aa'])
      .exclude('.third-party-widget') // Exclude third-party content
      .analyze()

    expect(accessibilityScanResults.violations).toEqual([])
  })

  test('should be navigable by keyboard only', async ({ page }) => {
    await page.goto('/chat')

    // Tab through main elements
    await page.keyboard.press('Tab') // Skip link
    await page.keyboard.press('Enter') // Activate skip link

    const focused = await page.evaluate(() => document.activeElement?.id)
    expect(focused).toBe('main-content')
  })
})

// .eslintrc.json additions
{
  "extends": ["plugin:jsx-a11y/recommended"],
  "rules": {
    "jsx-a11y/alt-text": "error",
    "jsx-a11y/anchor-has-content": "error",
    "jsx-a11y/aria-props": "error",
    "jsx-a11y/aria-proptypes": "error",
    "jsx-a11y/aria-unsupported-elements": "error",
    "jsx-a11y/click-events-have-key-events": "warn",
    "jsx-a11y/heading-has-content": "error",
    "jsx-a11y/html-has-lang": "error",
    "jsx-a11y/img-redundant-alt": "error",
    "jsx-a11y/interactive-supports-focus": "error",
    "jsx-a11y/label-has-associated-control": "error",
    "jsx-a11y/no-access-key": "error",
    "jsx-a11y/no-autofocus": "warn",
    "jsx-a11y/no-noninteractive-element-interactions": "warn",
    "jsx-a11y/no-redundant-roles": "error",
    "jsx-a11y/role-has-required-aria-props": "error",
    "jsx-a11y/role-supports-aria-props": "error",
    "jsx-a11y/tabindex-no-positive": "error"
  }
}

# .github/workflows/accessibility.yml
name: Accessibility Tests

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  a11y-lint:
    name: Accessibility Linting
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
        with:
          version: 9.15.4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'pnpm'
      - run: pnpm install
      - run: pnpm lint
        # Includes jsx-a11y rules

  a11y-unit:
    name: Accessibility Unit Tests
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
        with:
          version: 9.15.4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'pnpm'
      - run: pnpm install
      - run: pnpm test -- --testPathPattern="a11y"

  a11y-e2e:
    name: Accessibility E2E Tests
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
        with:
          version: 9.15.4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'pnpm'
      - run: pnpm install
      - run: npx playwright install --with-deps
      - run: pnpm build
      - run: pnpm test:e2e -- --grep "@a11y"

  lighthouse:
    name: Lighthouse Accessibility Audit
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
        with:
          version: 9.15.4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'pnpm'
      - run: pnpm install
      - run: pnpm build
      - name: Run Lighthouse
        uses: treosh/lighthouse-ci-action@v11
        with:
          configPath: '.lighthouserc.json'
          uploadArtifacts: true

## Screen Reader Test Script

### Page Load

1. [ ] Page title is announced
2. [ ] Main landmarks are identified
3. [ ] Skip link is first focusable element

### Navigation

1. [ ] All interactive elements are reachable via Tab
2. [ ] Tab order is logical
3. [ ] Focus indicator is visible
4. [ ] Skip links work correctly

### Messages

1. [ ] New messages are announced
2. [ ] Message content is readable
3. [ ] Reactions are announced
4. [ ] Timestamps are readable

### Forms

1. [ ] Labels are associated with inputs
2. [ ] Required fields are indicated
3. [ ] Error messages are announced
4. [ ] Success messages are announced

### Modals/Dialogs

1. [ ] Focus moves to modal on open
2. [ ] Focus is trapped within modal
3. [ ] Escape closes modal
4. [ ] Focus returns to trigger on close

## Keyboard Testing Checklist

### Global

- [ ] Tab navigates forward through page
- [ ] Shift+Tab navigates backward
- [ ] Enter activates buttons/links
- [ ] Space activates buttons/checkboxes
- [ ] Escape closes modals/menus

### Menus

- [ ] Arrow keys navigate menu items
- [ ] Enter selects item
- [ ] Escape closes menu
- [ ] Home/End jump to first/last item

### Lists

- [ ] Arrow keys navigate items
- [ ] Enter activates item
- [ ] Type-ahead search works

### Chat

- [ ] Can compose message
- [ ] Can send with Enter/Cmd+Enter
- [ ] Can navigate message history
- [ ] Can react with keyboard

• All 9 languages have 100% translation coverage
• All 6 namespaces complete for each language
• UI string extraction audit shows 0 hardcoded strings
• Translation validation CI passes
• RTL layout fully functional for Arabic
• Date/time formatting works for all locales
• Number formatting works for all locales
• Pluralization works for all locales

• All color contrast ratios meet AA requirements (4.5:1 text, 3:1 UI)
• All interactive elements keyboard accessible
• All images have alt text
• All forms have proper labels
• All errors identified programmatically
• Focus order is logical
• Focus indicators visible
• Skip links functional
• Screen reader testing passed on VoiceOver, NVDA, TalkBack

• jest-axe tests for all UI components
• Playwright a11y tests for all pages
• ESLint jsx-a11y rules passing
• Lighthouse accessibility score >= 90
• CI workflow running on all PRs
• Manual testing checklist completed

1. Accessibility Guidelines (/docs/accessibility.md)

   • Component accessibility patterns
   • ARIA usage guide
   • Keyboard interaction patterns
   • Testing guide

2. Translation Guide (/docs/translation-guide.md)

   • How to contribute translations
   • Key naming conventions
   • Pluralization rules
   • Review process

3. RTL Development Guide (/docs/rtl-guide.md)

   • CSS patterns for RTL
   • Component considerations
   • Testing RTL layouts

1. Manual Testing Scripts (/docs/qa/accessibility-testing.md)

   • Screen reader test scripts
   • Keyboard test scripts
   • Mobile accessibility tests

2. Compliance Checklist (/docs/qa/wcag-checklist.md)

   • Full WCAG 2.1 AA checklist with status

src/lib/i18n/
├── index.ts                 # Main exports
├── i18n-config.ts          # Configuration
├── translator.ts           # Translation engine
├── locales.ts              # Locale registry
├── language-detector.ts    # Detection logic
├── plurals.ts              # Pluralization
├── date-formats.ts         # Date formatting
├── number-formats.ts       # Number formatting
├── rtl.ts                  # RTL support
└── __tests__/              # Tests

src/locales/
├── en/                     # English (complete)
├── de/                     # German (complete)
├── ja/                     # Japanese (complete)
├── es/                     # Spanish (partial)
├── fr/                     # French (partial)
├── ar/                     # Arabic (partial, RTL)
├── zh/                     # Chinese (partial)
├── pt/                     # Portuguese (partial)
└── ru/                     # Russian (partial)

src/hooks/
├── use-translation.ts      # Translation hook
└── use-locale.ts           # Locale hook

src/stores/
└── locale-store.ts         # Zustand store

src/lib/accessibility/
├── index.ts                # Main exports
├── a11y-store.ts          # Settings store
├── a11y-utils.ts          # Utilities
├── use-announcer.ts       # Screen reader announcements
├── use-focus-management.ts # Focus utilities
├── use-reduced-motion.ts  # Motion preferences
└── use-roving-tabindex.ts # Keyboard navigation

src/lib/a11y/
├── index.ts               # Alternate exports
├── announcer.ts           # Announcements
├── color-contrast.ts      # Contrast checking
├── focus-manager.ts       # Focus management
├── keyboard-nav.ts        # Keyboard navigation
├── keyboard-navigation.ts # Additional nav
├── reduced-motion.ts      # Motion utilities
└── screen-reader.ts       # SR utilities

src/contexts/
└── accessibility-context.tsx # React context

src/hooks/
├── use-a11y.ts            # A11y hooks
└── use-focus-management.ts # Focus hooks

src/styles/
└── accessibility.css      # A11y styles

src/components/accessibility/
├── AccessibilityMenu.tsx  # Settings menu
├── AccessibilityProvider.tsx # Provider
├── accessible-icon.tsx    # Icon wrapper
├── focus-trap.tsx         # Focus trap
├── live-region.tsx        # Live region
├── skip-links.tsx         # Skip links
└── visually-hidden.tsx    # SR-only text

src/app/settings/accessibility/
└── page.tsx               # Settings page

# General pattern
{namespace}.{feature}.{element}.{variant}

# Examples
common.buttons.save
common.buttons.cancel
common.buttons.delete

chat.messages.send
chat.messages.edit
chat.messages.delete

chat.channels.create.title
chat.channels.create.description
chat.channels.create.submitButton

errors.network.offline
errors.network.timeout
errors.validation.required
errors.validation.email

auth.signIn.title
auth.signIn.emailLabel
auth.signIn.passwordLabel
auth.signIn.submitButton
auth.signIn.forgotPassword

# Pluralization
chat.messages.count_zero
chat.messages.count_one
chat.messages.count_other

# With context
common.greeting_morning
common.greeting_afternoon
common.greeting_evening

Document maintained by: nself-chat team Last updated: February 3, 2026 Next review: Before v0.9.1 release