# Converter-Map Translation System Guide

## Overview

The Converter-Map Translation System is an automated term translation feature integrated into the DevQMS Report Builder. It allows automatic translation of terms in Excel/PDF templates using predefined term mappings stored in the converter-map settings.

## How It Works

The system automatically detects and replaces term patterns in the following formats:
- `TERM_en` → Replaces with English equivalent
- `TERM_ru` → Replaces with Russian equivalent  
- `TERM_tr` → Replaces with Turkish equivalent (original term)
- `{TERM_en}` → Placeholder format for English
- `{TERM_ru}` → Placeholder format for Russian
- `{TERM_tr}` → Placeholder format for Turkish

## Setting Up Converter-Map

### 1. Access Converter-Map Settings

Navigate to **Admin Panel** → **Settings** → **Converter Map**

### 2. Add Translation Entries

Fill in the grid with your term translations:

| Term | Term_eng | Term_ru |
|------|----------|---------|
| STELLAR | here is STELLAR to_en equivalent | buraya STELLAR'ın to_ru karşılığı |
| WELD | Welding Process | Процесс сварки |
| INSPECTION | Quality Inspection | Контроль качества |

### 3. Save Changes

Click the **"Store Converter Map"** button to save your translations.

> **Note:** The system automatically clears the cache when you save changes, so translations are immediately available.

## Using Translations in Templates

### 1. Excel Template Usage

In your Excel templates, use the following patterns:

```excel
Cell A1: "STELLAR_en Procedure"
Result: "here is STELLAR to_en equivalent Procedure"

Cell B1: "Процедура STELLAR_ru"
Result: "Процедура buraya STELLAR'ın to_ru karşılığı"

Cell C1: "Test {WELD_en} Report"
Result: "Test Welding Process Report"
```

### 2. File Name Templates

Use translation patterns in file naming:

```
Template: "Report_STELLAR_en_{iso_number}.xlsx"
Result: "Report_here is STELLAR to_en equivalent_12345.xlsx"

Template: "{INSPECTION_ru}_Document_{date}.pdf"
Result: "Контроль качества_Document_2024-01-15.pdf"
```

### 3. PDF Content

The same patterns work in PDF content:
- Text blocks
- Headers and footers  
- Dynamic content areas
- Formula results

## Integration Points

The converter-map system is automatically applied at these stages:

### 1. Excel Processing
- **Before workPermitReplacerExcel2**: Spreadsheet-level replacements
- **After standard placeholders**: Cell-by-cell content replacement
- **In formulas**: Formula content translation

### 2. File Naming
- Applied to `fileNameTemplate` parameter
- Executed after standard placeholder replacement

### 3. Data Processing
- **Master data**: Template-level translations
- **Detail data**: Row-by-row translations in both single and multiple modes
- **Empty sections**: Cleanup translations for unused sections

## Advanced Features

### 1. Cache Management
- Translations are cached for 1 hour for performance
- Cache automatically clears when converter-map is updated
- Manual cache clearing: `Cache::forget('converter_map_data')`

### 2. Pattern Recognition
The system uses regex patterns to identify translation targets:
```php
// Word boundary patterns
/(\w+)_en\b/    // Matches: STELLAR_en, WELD_en
/(\w+)_ru\b/    // Matches: STELLAR_ru, WELD_ru  
/(\w+)_tr\b/    // Matches: STELLAR_tr, WELD_tr

// Placeholder patterns  
/\{(\w+)_en\}/  // Matches: {STELLAR_en}, {WELD_en}
/\{(\w+)_ru\}/  // Matches: {STELLAR_ru}, {WELD_ru}
/\{(\w+)_tr\}/  // Matches: {STELLAR_tr}, {WELD_tr}
```

### 3. Error Handling
- Non-existent terms remain unchanged
- System continues processing even if translation fails
- Comprehensive logging for debugging

## Best Practices

### 1. Term Naming Convention
- Use UPPERCASE for consistency
- Use descriptive, single-word terms when possible
- Example: `STELLAR`, `WELD`, `INSPECTION`, `PROCEDURE`

### 2. Translation Quality
- Ensure all three language fields are filled
- Use consistent terminology across documents
- Test translations in actual templates

### 3. Template Design
- Place translation patterns in appropriate contexts
- Consider text length differences between languages
- Test with actual data before production use

## Example Implementation

### 1. Complete Converter-Map Setup
```
Term: STELLAR
Term_eng: Stellar Development LLC
Term_ru: ООО Стеллар Девелопмент

Term: QC  
Term_eng: Quality Control
Term_ru: Контроль качества

Term: WELD
Term_eng: Welding
Term_ru: Сварка
```

### 2. Template Usage
```excel
// English Report Template
A1: "STELLAR_en QC_en Report"
A2: "WELD_en Inspection Results"

// Russian Report Template  
A1: "Отчет STELLAR_ru по QC_ru"
A2: "Результаты WELD_ru контроля"

// Mixed Language Template
A1: "Company: STELLAR_en"
A2: "Компания: STELLAR_ru" 
A3: "Process: {WELD_en}"
A4: "Процесс: {WELD_ru}"
```

### 3. Expected Results
```
English Output:
- "Stellar Development LLC Quality Control Report"
- "Welding Inspection Results"

Russian Output:
- "Отчет ООО Стеллар Девелопмент по Контроль качества"
- "Результаты Сварка контроля"

Mixed Output:
- "Company: Stellar Development LLC"
- "Компания: ООО Стеллар Девелопмент"
- "Process: Welding"  
- "Процесс: Сварка"
```

## Troubleshooting

### 1. Translations Not Working
- Check if converter-map entries are saved properly
- Verify term names match exactly (case-sensitive)
- Clear cache manually if needed: `Cache::forget('converter_map_data')`

### 2. Performance Issues
- Cache is enabled by default (1-hour TTL)
- Large converter-maps may impact initial load
- Consider splitting very large term lists

### 3. Pattern Conflicts
- Use word boundaries to prevent partial matches
- Test complex patterns in isolated templates first
- Check logs for replacement details

## Technical Implementation

The system consists of two main functions:

### 1. `converterMapReplacer()`
- Processes Excel/PDF spreadsheets
- Handles cell-by-cell replacement
- Returns modified spreadsheet object

### 2. `converterMapStringReplacer()`
- Processes string content
- Used for file names and text blocks
- Returns modified string

Both functions are automatically called during the report building process and require no manual intervention.

## Integration with Report Builder

The converter-map system is seamlessly integrated into the existing report builder workflow:

1. **Template Loading** → Standard Excel template loaded
2. **Work Permit Replacement** → Work permit placeholders processed  
3. **Converter-Map Translation** → Term translations applied
4. **Standard Placeholders** → Regular data placeholders processed
5. **Final Output** → PDF generation with all translations

This ensures that term translations work alongside all existing functionality without conflicts.