# Requirements Document

## Introduction

This feature adds automatic translation of German article titles to English using the Ollama AI service. The translation will occur during the article crawling process and both the original German title and English translation will be stored in the database. The newsletter will display the English title prominently with the original German title as a subtitle when available.

## Glossary

- **Crawler Service**: The Python service that fetches articles from RSS feeds and processes them
- **Ollama Client**: The Python client that communicates with the Ollama AI server for text processing
- **Article Document**: The MongoDB document structure that stores article data
- **Newsletter Template**: The HTML template used to render the email newsletter sent to subscribers
- **Translation Result**: The response object returned by the Ollama translation function containing the translated title and metadata

## Requirements

### Requirement 1

**User Story:** As a newsletter subscriber, I want to see article titles in English, so that I can quickly understand the content without knowing German

#### Acceptance Criteria

1. WHEN the Crawler Service processes an article, THE Ollama Client SHALL translate the German title to English
2. THE Article Document SHALL store both the original German title and the English translation
3. THE Newsletter Template SHALL display the English title as the primary heading
4. WHERE an English translation exists, THE Newsletter Template SHALL display the original German title as a subtitle
5. IF the translation fails, THEN THE Newsletter Template SHALL display the original German title as the primary heading

### Requirement 2

**User Story:** As a system administrator, I want translation to be integrated with the existing Ollama service, so that I don't need to configure additional services

#### Acceptance Criteria

1. THE Ollama Client SHALL provide a translate_title method that accepts a German title and returns an English translation
2. THE translate_title method SHALL use the same Ollama server configuration as the existing summarization feature
3. THE translate_title method SHALL use a temperature setting of 0.3 for consistent translations
4. THE translate_title method SHALL limit the response to 100 tokens maximum for title-length outputs
5. THE translate_title method SHALL return a Translation Result containing success status, translated title, error message, and duration

### Requirement 3

**User Story:** As a developer, I want translation errors to be handled gracefully, so that article processing continues even when translation fails

#### Acceptance Criteria

1. IF the Ollama server is unavailable, THEN THE Crawler Service SHALL continue processing articles without translations
2. IF a translation request times out, THEN THE Crawler Service SHALL log the error and store the article with only the original title
3. THE Crawler Service SHALL display translation status in the console output during crawling
4. THE Article Document SHALL include a translated_at timestamp field when translation succeeds
5. THE Article Document SHALL store NULL in the title_en field when translation fails

### Requirement 4

**User Story:** As a newsletter subscriber, I want translations to be accurate and natural, so that the English titles read fluently

#### Acceptance Criteria

1. THE Ollama Client SHALL provide a clear prompt instructing the model to translate German news headlines to English
2. THE Ollama Client SHALL instruct the model to provide only the translation without explanations
3. THE Ollama Client SHALL clean the translation output by removing quotes and extra text
4. THE Ollama Client SHALL extract only the first line of the translation response
5. THE Ollama Client SHALL trim whitespace from the translated title

### Requirement 5

**User Story:** As a system operator, I want to see translation performance metrics, so that I can monitor the translation feature effectiveness

#### Acceptance Criteria

1. THE Crawler Service SHALL log the translation duration for each article
2. THE Crawler Service SHALL display a success indicator when translation completes
3. THE Crawler Service SHALL display an error message when translation fails
4. THE Translation Result SHALL include the duration in seconds
5. THE Article Document SHALL store the translated_at timestamp for successful translations