citrus-cms/resources/views/guide/converter-map-system.md

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:

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:

// 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

// 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.