gurix/markusgraf_ch
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
cb5f33c5cb3c01640aabb48167685d1d777691e0
markusgraf_ch/openspec/changes/add-multilingual-support/specs/internationalization/spec.md
T
gurixandClaude c3c747b7fa feat: add multilingual support with German and English 
Implement complete multilingual support using Hugo's multilingual mode with German (de) as default and English (en) as secondary language.

Changes:
- Configure Hugo multilingual mode with language-specific parameters
- Reorganize content using language suffix pattern (filename.de.md, filename.en.md)
- Translate all content to English (home page and CV page)
- Implement language switcher that maintains page context
- Add language-specific navigation menus
- Update templates to use language-aware URL functions (relLangURL)
- Fix navbar brand and Home links to respect current language
- Add translationKey to content frontmatter for explicit translation linking

URL Structure:
- German: /de/ (home), /de/cv/ (CV page)
- English: /en/ (home), /en/cv/ (CV page)

Key Implementation Details:
- Use filename.{lang}.md pattern instead of {lang}/filename.md subdirectories
- Always use relLangURL for internal navigation, never .Site.BaseURL
- Menu URLs must include language prefix when defaultContentLanguageInSubdir = true
- Added translationKey to frontmatter for proper translation discovery

Documented 5 critical bugs and their solutions in design.md for future reference.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-27 23:52:08 +01:00

5.6 KiB
Raw Blame History

Internationalization

ADDED 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
Reference in New Issue View Git Blame Copy Permalink