markusgraf_ch/openspec/specs/internationalization/spec.md

# internationalization Specification

## Purpose
TBD - created by archiving change add-multilingual-support. Update Purpose after archive.
## Requirements
### Requirement: Multilingual Content Support
The site SHALL support multiple languages with German (de) as the default language and English (en) as a secondary language.

#### Scenario: German content is accessible at /de/ path
- **WHEN** a visitor navigates to `/de/` or any `/de/*` path
- **THEN** the page displays in German language
- **AND** all navigation, content, and UI elements are in German

#### Scenario: English content is accessible at /en/ path
- **WHEN** a visitor navigates to `/en/` or any `/en/*` path
- **THEN** the page displays in English language
- **AND** all navigation, content, and UI elements are in English

#### Scenario: All pages have translations
- **WHEN** content exists in one language
- **THEN** a corresponding translation SHALL exist in the other language
- **AND** the content structure mirrors across languages (e.g., `/de/cv` ↔ `/en/cv`)

### Requirement: Language Switcher
The site navigation SHALL include a language switcher that allows users to change languages while maintaining page context.

#### Scenario: Language switcher is visible in navigation
- **WHEN** a visitor views any page
- **THEN** the navigation displays language options (DE, EN)
- **AND** the current active language is visually indicated
- **AND** the inactive language is shown as a clickable link

#### Scenario: Language switching maintains page context
- **WHEN** a visitor is on `/de/cv` and clicks the English language link
- **THEN** the page navigates to `/en/cv` (the English version of the same page)
- **AND** the page content changes to English

#### Scenario: Language switching from home page
- **WHEN** a visitor is on `/de/` and clicks the English language link
- **THEN** the page navigates to `/en/`
- **AND** the home page content changes to English

#### Scenario: Language switcher handles missing translations
- **WHEN** a visitor is on a page without a translation
- **THEN** the language link points to the home page of the target language
- **AND** the user is not left on a broken or non-existent page

### Requirement: Language Persistence
The site SHALL maintain the user's language preference through URL-based routing without requiring cookies or JavaScript.

#### Scenario: Language preference persists across navigation
- **WHEN** a visitor navigates to `/de/cv` and then clicks a navigation link
- **THEN** all subsequent pages remain in German (e.g., clicking "Home" goes to `/de/`)
- **AND** the language preference is maintained through the URL structure

#### Scenario: Direct URL access respects language
- **WHEN** a visitor directly accesses `/en/cv` via URL or bookmark
- **THEN** the page displays in English
- **AND** all navigation links point to English pages

### Requirement: Browser Language Detection
The site configuration SHALL support automatic language selection based on browser language preferences for first-time visitors.

#### Scenario: Server redirect based on Accept-Language header
- **WHEN** a visitor accesses the root URL `/` for the first time
- **THEN** the server MAY redirect to `/de/` or `/en/` based on the browser's `Accept-Language` header
- **AND** German is used as the fallback if no language preference is detected

#### Scenario: URL-based access bypasses language detection
- **WHEN** a visitor directly accesses `/de/` or `/en/`
- **THEN** the specified language is used regardless of browser settings
- **AND** no redirect occurs

### Requirement: Content Translation
All site content SHALL be translated between German and English languages.

#### Scenario: Home page content is translated
- **WHEN** viewing the home page in German (`/de/`)
- **THEN** all text including introduction, project descriptions, and UI labels are in German
- **WHEN** viewing the home page in English (`/en/`)
- **THEN** all text including introduction, project descriptions, and UI labels are in English

#### Scenario: CV page content is translated
- **WHEN** viewing the CV page in German (`/de/cv`)
- **THEN** all text including headings, instructions, and contact information are in German
- **WHEN** viewing the CV page in English (`/en/cv`)
- **THEN** all text including headings, instructions, and contact information are in English

#### Scenario: Navigation menu is translated
- **WHEN** viewing any page in German
- **THEN** navigation menu items are in German (e.g., "Lebenslauf" for CV)
- **WHEN** viewing any page in English
- **THEN** navigation menu items are in English (e.g., "Curriculum Vitae" for CV)

#### Scenario: Footer content is translated
- **WHEN** viewing any page in German
- **THEN** footer content including address and contact information labels are in German
- **WHEN** viewing any page in English
- **THEN** footer content including address and contact information labels are in English

### Requirement: SEO and Accessibility
The site SHALL implement proper multilingual SEO practices and accessibility features.

#### Scenario: HTML lang attribute is set correctly
- **WHEN** viewing a German page
- **THEN** the HTML element has `lang="de"` attribute
- **WHEN** viewing an English page
- **THEN** the HTML element has `lang="en"` attribute

#### Scenario: Alternative language links are provided
- **WHEN** viewing any page
- **THEN** the HTML head includes `<link rel="alternate" hreflang="de" ...>` and `<link rel="alternate" hreflang="en" ...>` tags
- **AND** these tags point to the corresponding page in each language

#### Scenario: Page titles reflect language
- **WHEN** viewing a page in German
- **THEN** the page title is in German
- **WHEN** viewing a page in English
- **THEN** the page title is in English