markusgraf_ch/openspec/changes/archive/2025-11-25-add-dialogbasierte-anwendungen-post/specs/blog-post-dialogbasierte-anwendungen/spec.md

# Spec: Blog Post - Dialogbasierte Anwendungen

## Overview

Specification for the bilingual blog post "Computer, ..." about dialog-based applications using language models. Uses translated URL slugs with separate directories linked via translationKey.

## ADDED Requirements

### Requirement: Blog post directory structure with translated slugs

The blog post MUST exist in separate directories for German and English with appropriate URL slugs.

**Rationale**: Using translated slugs provides better SEO and user experience, with language-appropriate URLs.

#### Scenario: Directories created with translated slugs

**Given** the Hugo content directory structure
**When** creating the new blog post
**Then** a directory `content/blog/dialogbasierte-anwendungen/` must exist for German
**And** a directory `content/blog/dialog-based-applications/` must exist for English
**And** German directory must contain `index.de.md`
**And** English directory must contain `index.en.md`
**And** both files must include `translationKey: "dialogbasierte-anwendungen-post"` in frontmatter

---

### Requirement: German blog post content

The German version MUST accurately represent the Notion source content.

**Rationale**: Preserve the original German text exactly as written by the author.

#### Scenario: German content matches Notion source

**Given** the Notion page content at https://www.notion.so/Computer-2b5c4dc46de08053954ff3a14b171b47
**When** creating the German blog post file
**Then** the content must match the Notion source text
**And** all formatting (headings, lists, emphasis) must be preserved
**And** all external links must be preserved
**And** the TL;DR section must be included
**And** the Codeberg repository link must be included

#### Scenario: German frontmatter is correct

**Given** the blog post requirements
**When** creating the German blog post
**Then** the frontmatter must use YAML format (three dashes)
**And** must include `title: "Computer, …"`
**And** must include `date: 2025-11-25`
**And** must include `translationKey: "dialogbasierte-anwendungen-post"`
**And** must include a `description` field with appropriate summary text
**And** must be valid YAML syntax

---

### Requirement: English blog post translation

The English version MUST be a natural, accurate translation of the German content.

**Rationale**: Make the content accessible to English-speaking readers while maintaining technical accuracy and readability.

#### Scenario: English translation is natural and accurate

**Given** the German blog post content
**When** creating the English translation
**Then** the translation must convey the same meaning as the German original
**And** must use natural English phrasing and idioms
**And** must maintain technical accuracy for all concepts
**And** must preserve the same structure (sections, lists)
**And** Star Trek references must be preserved (universally known)

#### Scenario: English frontmatter is correct

**Given** the blog post requirements
**When** creating the English blog post
**Then** the frontmatter must use YAML format (three dashes)
**And** must include `title` with natural English translation
**And** must include `date: 2025-11-25` (same as German)
**And** must include `translationKey: "dialogbasierte-anwendungen-post"`
**And** must include a `description` field with English summary
**And** must be valid YAML syntax

#### Scenario: External links are adapted appropriately

**Given** external reference links in the German version
**When** creating the English translation
**Then** Wikipedia links should point to English Wikipedia versions where applicable
**And** code repository links (Codeberg) must remain unchanged
**And** all links must be functional

---

### Requirement: Content formatting and structure

Both versions MUST use proper markdown formatting consistent with Hugo blog posts.

**Rationale**: Ensure consistent rendering and readability across the blog.

#### Scenario: Markdown structure is correct

**Given** the blog post content
**When** creating the blog post files
**Then** headings must use proper markdown hierarchy (##, ###)
**And** lists must use proper markdown syntax
**And** links must use markdown link syntax `[text](url)`
**And** emphasis must use proper markdown (*italic*, **bold**)
**And** code references must use inline code backticks where appropriate

#### Scenario: Special characters are handled correctly

**Given** the blog post contains German umlauts and special characters
**When** creating the blog post files
**Then** files must be saved with UTF-8 encoding
**And** all special characters must render correctly (ä, ö, ü, ß, …)

---

### Requirement: Hugo build compatibility

The blog posts MUST build successfully with Hugo and render correctly.

**Rationale**: Ensure the content integrates properly with the existing Hugo site.

#### Scenario: Hugo builds successfully

**Given** the new blog post files
**When** running `hugo build`
**Then** the build must complete without errors
**And** no warnings related to the new blog post must be generated

#### Scenario: Blog posts are accessible at correct translated URLs

**Given** a successful Hugo build
**When** viewing the site
**Then** the German version must be accessible at `/de/blog/dialogbasierte-anwendungen/`
**And** the English version must be accessible at `/en/blog/dialog-based-applications/`

#### Scenario: Blog posts appear in blog listings

**Given** a successful Hugo build
**When** viewing the blog index pages
**Then** the new post must appear in the German blog listing at `/de/blog/`
**And** the new post must appear in the English blog listing at `/en/blog/`
**And** the post must display with correct title and description

#### Scenario: Language switcher works correctly

**Given** both language versions with matching translationKey
**When** viewing either version of the blog post
**Then** the language switcher must link to the corresponding translation
**And** switching from German to English must navigate to `/en/blog/dialog-based-applications/`
**And** switching from English to German must navigate to `/de/blog/dialogbasierte-anwendungen/`

---

### Requirement: Content validation

The implementation MUST pass OpenSpec validation.

**Rationale**: Ensure compliance with project standards and specification requirements.

#### Scenario: OpenSpec validation passes

**Given** the completed implementation
**When** running `openspec validate add-dialogbasierte-anwendungen-post --strict`
**Then** validation must pass with no errors
**And** no warnings should be generated