clawfort/openspec/specs/language-aware-content-delivery/spec.md

Purpose

Canonical specification for language-aware-content-delivery requirements synced from OpenSpec change deltas.

Requirements

Requirement: API supports language-aware content retrieval

The system SHALL support language-aware content delivery for hero and feed reads using selected language input.

Scenario: Language-specific latest article response

• WHEN a client requests latest article data with a supported language selection
• THEN the system returns headline and summary in the selected language when available
• AND includes the corresponding base article metadata and media attribution

Scenario: Language-specific paginated feed response

• WHEN a client requests paginated feed data with a supported language selection
• THEN the system returns each feed item's headline and summary in the selected language when available
• AND preserves existing pagination behavior and ordering semantics

Scenario: Tamil and Malayalam rendering quality support

• WHEN Tamil (ta) or Malayalam (ml) content is delivered to frontend surfaces
• THEN payload text preserves script fidelity and Unicode correctness
• AND frontend presentation hooks can apply readability-focused typography adjustments without changing response shape

Requirement: Language fallback to English is deterministic

The system SHALL return English source content when the requested translation is unavailable or fails translation quality validation.

Scenario: Missing translation fallback

• WHEN a client requests Tamil or Malayalam content for an article lacking that translation
• THEN the system returns the English headline and summary for that article
• AND response shape remains consistent with language-aware responses

Scenario: Invalid translation fallback

• WHEN a client requests Tamil or Malayalam content for an article whose translation failed quality validation
• THEN the system returns English headline and summary for that article
• AND avoids returning invalid translated output

Scenario: Unsupported language handling

• WHEN a client requests a language outside supported values (en, ta, ml)
• THEN the system applies the defined default language behavior for this phase
• AND avoids breaking existing consumers of news endpoints