Ümit Tunç
231 lines
6.8 KiB
Markdown
231 lines
6.8 KiB
Markdown
# 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. |