Math question templates

src/lib/
├── mathQuestionTemplates.ts # Math-specific template definitions
├── mathQuestionTemplateGenerator.ts # Math question generation logic
└── mathQuestionGenerator.ts # Updated with template integration

src/components/
└── MathQuestionTemplateDemo.tsx # Interactive demo component

src/app/
└── math-templates-demo/ # Demo page
 └── page.tsx
```text

## Core Components

### 1. Math Question Templates (`mathQuestionTemplates.ts`)

Defines specialized math templates with proper operation translations:

```typescript
export const MATH_QUESTION_TEMPLATES: QuestionTemplate[] = [
 {
 id: 'math-addition-basic',
 type: 'math',
 category: 'arithmetic',
 difficulty: 'easy',
 template: {
 english: 'What is {firstNumber} plus {secondNumber} in Kifuliiru?',
 kifuliiru: 'Ni iki {firstNumberKifuliiru} kuyongera {secondNumberKifuliiru}?',
 kiswahili: 'Ni nini {firstNumberKiswahili} jumlisha {secondNumberKiswahili} katika Kifuliiru?',
 french: 'Qu\'est-ce que {firstNumber} plus {secondNumber} en Kifuliiru?'
 },
 // ... placeholders and answer format
 }
];
```text

### 2. Math Question Generator (`mathQuestionTemplateGenerator.ts`)

Handles math-specific question generation with proper translations:

```typescript
// Generate math question with proper translations
export const generateMathQuestionFromTemplate = (
 templateId?: string,
 difficulty: 'easy' | 'medium' | 'hard' = 'easy'
): QuestionInstance => {
 // Generates question with proper number and operation translations
};

// Generate multiple choice math question
export const generateMultipleChoiceMathQuestion = (
 templateId?: string,
 difficulty: 'easy' | 'medium' | 'hard' = 'easy'
): QuestionInstance => {
 // Generates multiple choice with wrong answers
};

// Generate word problem
export const generateWordProblemMathQuestion = (
 difficulty: 'easy' | 'medium' | 'hard' = 'medium'
): QuestionInstance => {
 // Generates contextual word problems
};
```text

## Available Math Templates

### Basic Operations

1. **Addition (kuyongera)**
 - Template ID: `math-addition-basic`
 - Difficulty: Easy
 - Example: "What is 5 plus 3 in Kifuliiru?"

2. **Subtraction (kushaaza)**
 - Template ID: `math-subtraction-basic`
 - Difficulty: Easy
 - Example: "What is 10 minus 4 in Kifuliiru?"

3. **Multiplication (kuluza)**
 - Template ID: `math-multiplication-basic`
 - Difficulty: Medium
 - Example: "What is 6 times 7 in Kifuliiru?"

4. **Division (kugabura)**
 - Template ID: `math-division-basic`
 - Difficulty: Medium
 - Example: "What is 20 divided by 4 in Kifuliiru?"

### Question Formats

1. **Multiple Choice**
 - Template ID: `math-addition-multiple-choice`
 - Provides 4 options with correct answer

2. **Text to Numbers (Fill in the blank)**
 - Template ID: `math-text-to-numbers`
 - Example: "Complete: 5 kuyongera 3 = ___"

3. **Numbers to Text (Write the equation)**
 - Template ID: `math-numbers-to-text`
 - Example: "Write in Kifuliiru: 5 + 3 = 8"

4. **Word Problems**
 - Template ID: `math-word-problem-addition`
 - Contextual problems with items and scenarios

## Number Translation System

### Automatic Translation
The system automatically translates numbers using the existing `numberTranslations.ts`:

```typescript
import { numberToKifuliiru } from './numberTranslations';

const kifuliiruNumber = numberToKifuliiru(25); // "makumi gabiri na butanu"
```text

### Operation Translations
Mathematical operations are translated consistently:

```typescript
const operations = {
 english: { '+': 'plus', '-': 'minus', '×': 'times', '÷': 'divided by' },
 kifuliiru: { '+': 'kuyongera', '-': 'kushaaza', '×': 'kuluza', '÷': 'kugabura' },
 kiswahili: { '+': 'jumlisha', '-': 'toa', '×': 'zidisha', '÷': 'gawanya' },
 french: { '+': 'plus', '-': 'moins', '×': 'fois', '÷': 'divisé par' }
};
```text

## Difficulty Levels

### Easy (Gufi)
- **Number Range**: 1-20
- **Operations**: Basic addition and subtraction
- **Examples**: 5 + 3, 10 - 4

### Medium (Hagati)
- **Number Range**: 1-50
- **Operations**: All operations including multiplication and division
- **Examples**: 6 × 7, 20 ÷ 4

### Hard (Bikomeye)
- **Number Range**: 1-100
- **Operations**: Complex problems and word problems
- **Examples**: Word problems with multiple steps

## Usage Examples

### Basic Usage

```typescript
import { 
 generateMathTemplateQuestions,
 generateMathTemplateQuestion,
 generateMathMultipleChoiceQuestion,
 generateMathWordProblem
} from '@/lib/mathQuestionGenerator';

// Generate multiple questions
const questions = generateMathTemplateQuestions(5, 'easy');

// Generate single question
const question = generateMathTemplateQuestion('math-addition-basic', 'medium');

// Generate multiple choice question
const mcQuestion = generateMathMultipleChoiceQuestion(undefined, 'easy');

// Generate word problem
const wordProblem = generateMathWordProblem('medium');
```text

### Advanced Usage

```typescript
import { generateMathQuestionSet } from '@/lib/mathQuestionTemplateGenerator';

// Generate complete question set
const questionSet = generateMathQuestionSet(10, 'hard', 'arithmetic');

console.log(questionSet.length); // 10 questions
console.log(questionSet[0].question.kifuliiru); // "Ni iki 15 kuyongera 8?"
```text

### Display Questions

```typescript
import { formatQuestionForDisplay } from '@/lib/enhancedQuestionGenerator';

const question = generateMathTemplateQuestion();
const display = formatQuestionForDisplay(question, 'kifuliiru');

console.log(display.question); // "Ni iki 5 kuyongera 3?"
console.log(display.answer); // "Igisubizo ni 8"
```text

## Demo Component

### Interactive Demo
Use the `MathQuestionTemplateDemo` component to test the system:

```tsx
import MathQuestionTemplateDemo from '@/components/MathQuestionTemplateDemo';

export default function TestPage() {
 return <MathQuestionTemplateDemo />;
}
```text

### Demo Features
- **Configuration Panel**: Set difficulty, count, and language
- **Template Browser**: View and test individual templates
- **Question Navigation**: Navigate through generated questions
- **Answer Checking**: Real-time answer validation
- **Multi-language Display**: Switch between languages
- **Audio Support**: Text-to-speech for questions

## Template Customization

### Adding New Math Templates

1. **Define the Template**:
```typescript
const newMathTemplate: QuestionTemplate = {
 id: 'math-custom-operation',
 type: 'math',
 category: 'custom',
 difficulty: 'medium',
 template: {
 english: 'What is {firstNumber} {operation} {secondNumber} in Kifuliiru?',
 kifuliiru: 'Ni iki {firstNumberKifuliiru} {operationKifuliiru} {secondNumberKifuliiru}?',
 kiswahili: 'Ni nini {firstNumberKiswahili} {operationKiswahili} {secondNumberKiswahili} katika Kifuliiru?',
 french: 'Qu\'est-ce que {firstNumber} {operationFrench} {secondNumber} en Kifuliiru?'
 },
 placeholders: {
 // Define placeholders
 },
 answerFormat: {
 // Define answer format
 }
};
```text

2. **Add to Template Array**:
```typescript
export const MATH_QUESTION_TEMPLATES: QuestionTemplate[] = [
 // ... existing templates
 newMathTemplate
];
```text

3. **Create Generator Function**:
```typescript
export const generateCustomMathQuestion = (
 difficulty: 'easy' | 'medium' | 'hard' = 'medium'
): QuestionInstance => {
 return generateMathQuestionFromTemplate('math-custom-operation', difficulty);
};
```text

### Modifying Existing Templates

1. **Update Template Definition**:
```typescript
// In mathQuestionTemplates.ts
const updatedTemplate = {
 ...existingTemplate,
 template: {
 ...existingTemplate.template,
 kifuliiru: 'Updated Kifuliiru question: {firstNumberKifuliiru} {operationKifuliiru} {secondNumberKifuliiru}?'
 }
};
```text

2. **Test Changes**:
```typescript
const question = generateMathTemplateQuestion('math-addition-basic', 'easy');
console.log(question.question.kifuliiru); // Updated question
```text

## Language Support

### Supported Languages
- **English**: Base language for templates
- **Kifuliiru**: Primary target language with proper number and operation translations
- **Kiswahili**: East African language support
- **French**: International language support

### Translation Quality
- **Numbers**: Uses comprehensive `numberTranslations.ts` system
- **Operations**: Consistent operation translations across all languages
- **Context**: Cultural context considered in translations
- **Grammar**: Proper grammatical structure for each language

## Performance Considerations

### Optimization Tips
1. **Cache Templates**: Store frequently used templates in memory
2. **Lazy Loading**: Load templates only when needed
3. **Batch Generation**: Generate multiple questions in single call
4. **Template Validation**: Validate templates before use

### Memory Usage
- **Template Storage**: Minimal memory footprint
- **Question Generation**: Efficient placeholder replacement
- **Translation Caching**: Cached number translations

## Testing

### Unit Tests
```typescript
import { generateMathTemplateQuestion } from '@/lib/mathQuestionGenerator';

describe('Math Question Templates', () => {
 test('generates addition question', () => {
 const question = generateMathTemplateQuestion('math-addition-basic', 'easy');
 expect(question.question.kifuliiru).toContain('kuyongera');
 expect(question.correctAnswer.kifuliiru).toBeDefined();
 });
});
```text

### Integration Tests
```typescript
import { generateMathQuestionSet } from '@/lib/mathQuestionTemplateGenerator';

describe('Math Question Set Generation', () => {
 test('generates complete question set', () => {
 const questions = generateMathQuestionSet(5, 'medium');
 expect(questions).toHaveLength(5);
 expect(questions[0].metadata.difficulty).toBe('medium');
 });
});
```text

## Common Issues

### Template Not Found
```typescript
try {
 const question = generateMathTemplateQuestion('invalid-template-id');
} catch (error) {
 console.error('Template not found:', error.message);
}
```text

### Missing Placeholders
```typescript
import { validateMathTemplatePlaceholders } from '@/lib/mathQuestionTemplateGenerator';

const validation = validateMathTemplatePlaceholders('math-addition-basic', {
 firstNumber: 5,
 secondNumber: 3
 // Missing other required placeholders
});

if (!validation.valid) {
 console.error('Missing placeholders:', validation.missing);
}
```text

### Translation Errors
```typescript
// Check if number translation is working
import { numberToKifuliiru } from '@/lib/numberTranslations';

const translation = numberToKifuliiru(25);
if (translation === '25') {
 console.warn('Number translation may not be working properly');
}
```text

## Success!

The Math Question Templates system provides a robust, maintainable foundation for generating mathematical questions with proper Kifuliiru translations. With structured templates and automatic translation, you can create engaging math learning experiences that teach both mathematics and Kifuliiru language skills.

### Key Benefits
- **Consistent Quality**: All questions follow the same structure and translation patterns
- **Easy Maintenance**: Add new question types by creating templates
- **Cultural Accuracy**: Proper Kifuliiru mathematical terminology
- **Educational Value**: Teaches both math and language skills
- **Scalable**: Easy to extend with new templates and question types

Happy math question generating!