Initial Commit

openspec/changes/p03-languages-ml-tm/specs/article-translations-ml-tm/spec.md

@@ -0,0 +1,27 @@
+## ADDED Requirements
+
+### Requirement: System generates Tamil and Malayalam translations at article creation time
+The system SHALL generate Tamil (`ta`) and Malayalam (`ml`) translations for each newly created article during ingestion.
+
+#### Scenario: Translation generation for new article
+- **WHEN** a new source article is accepted for storage
+- **THEN** the system requests Tamil and Malayalam translations for headline and summary
+- **AND** translation generation occurs in the same ingestion flow for that article
+
+#### Scenario: Translation failure fallback
+- **WHEN** translation generation fails for one or both target languages
+- **THEN** the system stores the base article in English
+- **AND** marks missing translations as unavailable without failing the whole ingestion cycle
+
+### Requirement: System stores translation variants linked to the same article
+The system SHALL persist language-specific translated content as translation items associated with the base article.
+
+#### Scenario: Persist linked translations
+- **WHEN** Tamil and Malayalam translations are generated successfully
+- **THEN** the system stores them as language-specific content variants linked to the base article identifier
+- **AND** translation records remain queryable by language code
+
+#### Scenario: No duplicate translation variants per language
+- **WHEN** translation storage is attempted for an article-language pair that already exists
+- **THEN** the system avoids creating duplicate translation items for the same language
+- **AND** preserves one authoritative translation variant per article per language in this phase

openspec/changes/p03-languages-ml-tm/specs/language-aware-content-delivery/spec.md

@@ -0,0 +1,27 @@
+## ADDED 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
+
+### Requirement: Language fallback to English is deterministic
+The system SHALL return English source content when the requested translation is unavailable.
+
+#### 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: 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

openspec/changes/p03-languages-ml-tm/specs/language-preference-persistence/spec.md

@@ -0,0 +1,27 @@
+## ADDED Requirements
+
+### Requirement: Landing page provides language selector
+The system SHALL display a language selector on the landing page that allows switching between English, Tamil, and Malayalam content views.
+
+#### Scenario: User selects language from landing page
+- **WHEN** a user chooses Tamil or Malayalam from the language selector
+- **THEN** hero and feed content update to requested language-aware rendering
+- **AND** subsequent API requests use the selected language context
+
+#### Scenario: User switches back to English
+- **WHEN** a user selects English in the language selector
+- **THEN** content renders in English
+- **AND** language state updates immediately in the frontend view
+
+### Requirement: User language preference is persisted and restored
+The system SHALL persist selected language preference in client-side storage and restore it for returning users.
+
+#### Scenario: Persist language selection
+- **WHEN** a user selects a supported language on the landing page
+- **THEN** the selected language code is stored in local storage or a client cookie
+- **AND** the persisted value is used as preferred language for future visits on the same browser
+
+#### Scenario: Restore preference on return visit
+- **WHEN** a returning user opens the landing page
+- **THEN** the system reads persisted language preference from client storage
+- **AND** initializes the UI and content requests with that language by default