translations

MikoPBX Translation Managing

Translation management for the MikoPBX telephony system across 29 languages with Russian-first workflow.

What This Skill Does

• Adds new translation keys to Russian (ru/) files
• Translates Russian keys to all 28 other languages using AI
• Validates translation consistency across all languages
• Removes obsolete translation keys from all languages
• Creates new translation module files

When to Use

• Adding translations for new features or UI elements
• Translating Russian keys to all supported languages
• Checking translation consistency across languages
• Removing deprecated or unused translation keys
• Creating new translation modules for major features
• Fixing translation typos or errors
• Debugging missing translation issues

Quick Start

File Structure

src/Common/Messages/
├── ru/              ⭐ PRIMARY - Edit ONLY this
│   ├── ApiKeys.php
│   ├── Extensions.php
│   └── ... (all modules)
├── en/              🌐 Auto-translated
├── es/              🌐 Auto-translated
└── [27 more langs]  🌐 Auto-translated

Golden Rule

Developers ONLY modify Russian (ru/*.php) translations. All other languages are translated via:

• https://weblate.mikopbx.com (automatic sync)
• AI assistance (this skill)

Critical Process Rules

File-by-File Processing

ONE FILE AT A TIME: Never attempt to translate multiple files simultaneously. Complete one file fully (all languages) before moving to the next file.

Sequential Language Processing

PROCESS LANGUAGES SEQUENTIALLY: Complete one language fully (analysis → translation → merge → validation → reset) before starting the next language.

Validation After Each Step

ALWAYS VERIFY KEY COUNT: After processing each language, verify the key count matches Russian source EXACTLY. Stop if mismatch occurs.

Preserve Existing Work

NEVER OVERWRITE EXISTING TRANSLATIONS: Only translate missing keys. Preserve all existing correct translations.

Context Isolation

RESET CONTEXT BETWEEN LANGUAGES: Clear working variables and context after each language to prevent contamination or carry-over.

Error Handling

• Key count mismatch: STOP, report issue, do not proceed
• PHP syntax error: STOP, fix error before continuing
• Placeholder mismatch: STOP, correct translation
• Duplicate keys in source: Report and await instructions

Core Translation Rules

1. Placeholder Format

ALWAYS use %variable% format:

// ✅ CORRECT
'gs_PasswordLength' => 'Пароль: %length% из %max% символов'

// ❌ WRONG
'gs_PasswordLength' => 'Пароль: {length} из {max} символов'

2. Technical Terms (Never Translate)

Keep these unchanged across ALL languages:

SIP, IAX, AMI, AJAM, PJSIP, NAT, STUN, TURN, RTP, CDR, IVR,
DID, CID, DTMF, codec, trunk, extension, IP, DNS, VPN

Example:

// Russian
'pr_SipProviderSettings' => 'Настройки SIP провайдера'

// Thai - SIP stays the same
'pr_SipProviderSettings' => 'การตั้งค่าผู้ให้บริการ SIP'

3. Quote Escaping

Escape quotes properly for PHP:

// ✅ CORRECT
'msg_Example' => 'He said: "Don\'t forget"'

// ❌ WRONG - breaks PHP
'msg_Example' => 'He said: "Don't forget"'

4. Consistency Requirement

All languages MUST have:

• ✅ Identical translation keys
• ✅ Identical file structure
• ✅ Same placeholder names
• ✅ Same array structure

Example: If Russian has 157 keys in ApiKeys.php, ALL 28 other languages must have exactly 157 keys in ApiKeys.php.

5. Standalone Module Catalogs

For external modules, every Messages/<locale>.php file MUST directly return a standalone literal array:

<?php

declare(strict_types=1);

return [
    'module_example_Title' => 'Example',
];

Do not use require, include, variables, function calls, array_keys, array_combine, merges, or any other runtime composition. MikoPBX loads and processes each locale catalog itself.

Working with Large Files (Batch Processing)

When to Use Batch Mode

Files are automatically processed in batch mode when they have:

• > 300 translation keys (missing in target language)
• Average value length > 100 characters (complex technical descriptions)
• Files like: RestApi.php (1962 keys), Common.php (700+ keys), GeneralSettings.php (500+ keys)

Batch Processing Strategy

Automatic Detection:

# Check if file needs batching
php .claude/skills/translations/helpers/translation-batch-manager.php analyze src/Common/Messages/ru/Common.php en

Key Thresholds:

• Files < 150 keys → Direct mode (process all at once)
• Files 150-300 keys → Optional batching (based on complexity)
• Files > 300 keys → Batch mode required (100 keys per batch)

Batch Processing Workflow

When translating large files, follow this sequential batch workflow:

1. Analysis Phase:

# Analyze target file to determine batching strategy
php translation-batch-manager.php analyze src/Common/Messages/ru/RestApi.php en

Output tells you:

• Total missing keys
• Whether batching is needed
• Number of batches required
• Average value length

2. Split Phase:

# Create batches (saved to .claude/temp/batches/)
php translation-batch-manager.php split src/Common/Messages/ru/RestApi.php en 100

Creates JSON files:

• .claude/temp/batches/en_RestApi/batch_1.json (keys 1-100)
• .claude/temp/batches/en_RestApi/batch_2.json (keys 101-200)
• ... etc

3. Translation Phase (Repeat for each batch):

For each batch file:

1. Read batch JSON file
2. Extract keys object (Russian key-value pairs)
3. Translate ONLY those keys using AI
4. Preserve technical terms (SIP, PBX, CDR, etc.)
5. Keep %placeholder% format identical
6. Escape quotes properly

4. Merge Phase (After each batch translation):

# Merge translated batch into target file
php translation-batch-manager.php merge src/Common/Messages/en/RestApi.php batch_1_translated.json

This command:

• Merges new translations with existing ones
• Maintains key order from Russian source
• Creates backup (.backup file)
• Validates PHP syntax

5. Validation Phase (After each merge):

# Validate merged result
php translation-batch-manager.php validate src/Common/Messages/en/RestApi.php src/Common/Messages/ru/RestApi.php

Checks:

• PHP syntax is valid
• Key count matches Russian source
• No missing keys
• No extra keys
• Placeholders match exactly

6. Context Reset: After completing each batch:

• Clear working variables
• Log progress
• DO NOT carry over data to next batch

Batch Translation Example

Input batch JSON:

{
  "batch_num": 1,
  "total_batches": 20,
  "keys": {
    "rest_ApiKeys_ApiDescription": "Comprehensive API key management...",
    "rest_Extensions_CreateEndpoint": "Create a new PBX extension...",
    ...
  }
}

Translate keys → Save as batch_1_translated.json:

{
  "batch_num": 1,
  "total_batches": 20,
  "keys": {
    "rest_ApiKeys_ApiDescription": "Comprehensive API key management...",
    "rest_Extensions_CreateEndpoint": "Create a new PBX extension...",
    ...
  }
}

Merge into target file:

php translation-batch-manager.php merge src/Common/Messages/en/RestApi.php batch_1_translated.json

Progress Tracking with TodoWrite

When processing large files, create detailed task lists:

[1/28] English (en) - RestApi.php
  [1/20] ✓ Batch 1 (keys 1-100) - Translated & merged
  [2/20] ⏳ Batch 2 (keys 101-200) - In progress
  [3/20] ⏸ Batch 3 (keys 201-300) - Pending
  ...
  [20/20] ⏸ Batch 20 (keys 1901-1962) - Pending

[2/28] German (de) - RestApi.php
  [1/20] ⏸ Batch 1 (keys 1-100) - Pending
  ...

Critical Batch Mode Rules

1. One Batch at a Time: Complete translation → merge → validate before next batch
2. Incremental Progress: Each batch is independently saved and validated
3. Context Isolation: Reset AI context between batches to prevent contamination
4. Validation After Each Batch: Never skip validation between batches
5. Resume Capability: If error occurs, can resume from last successful batch

Error Handling in Batch Mode

PHP Syntax Error in Merged File:

• STOP immediately
• Restore from .backup file
• Fix translation in batch JSON
• Re-run merge command

Key Count Mismatch After Merge:

• STOP immediately
• Check batch JSON for duplicate keys
• Validate batch JSON format
• Re-run merge with corrected batch

Placeholder Format Error:

• Fix translation in batch JSON
• Re-run merge command
• Validate placeholders match

Helper Script Reference

Commands:

# Analyze file
php translation-batch-manager.php analyze <ru_file> <target_lang>

# Split into batches
php translation-batch-manager.php split <ru_file> <target_lang> [batch_size]

# Merge batch
php translation-batch-manager.php merge <target_file> <batch_json>

# Validate result
php translation-batch-manager.php validate <target_file> <ru_file>

# Check status
php translation-batch-manager.php status <ru_file> <target_lang>

All commands output JSON for easy parsing by agents.

Temporary Files Location

Batch files are stored in .claude/temp/batches/ (gitignored):

.claude/temp/batches/
├── en_RestApi/
│   ├── batch_1.json
│   ├── batch_2.json
│   └── ...
├── de_Common/
│   ├── batch_1.json
│   └── ...

Common Tasks

Task 1: Add New Translations (Russian Only)

Quick workflow:

1. Determine module and prefix (see prefixes.md)
2. Read existing Russian file
3. Add new keys with proper prefix
4. Maintain alphabetical order
5. Use Edit tool to save changes

Example:

// ru/ApiKeys.php
return [
    // ... existing keys

    // API Key Permissions (new feature)
    'ak_PermissionsTitle' => 'Разрешения API ключа',
    'ak_PermissionRead' => 'Чтение',
    'ak_PermissionWrite' => 'Запись',
];

After adding:

• Report what was added
• Remind about cache clearing
• R

---

Content truncated.