LocalizeAdder QT

Přehled

LocalizeAdder_QT je profesionální All-in-One Localization Manager pro audit, validaci, opravu a vícejazyčný překlad lokalizačních souborů. Nástroj podporuje jak starou Python-based strukturu (.py) tak nový moderní textový formát (.localize).

• Audit lokalizačních souborů: Statistiky, porovnání jazyků, kontrola integrity
• Automatizovaný překlad: 6 providerů s intelligentním fallbackem
• Validace struktury: Detekce duplicit, chybějících klíčů, strukturálních problémů
• Synchronizace jazyků: Automatická oprava a synchronizace
• Management nových jazyků: Přidání s automatickým překladem ze 60+ jazyků
• grafické rozhraní + dávkový režim: Profesionální Qt5 grafické rozhraní pro operátory, dávkový režim pro automatizaci

Funkce

grafické rozhraní Layout, Ovládání & Klávesové zkratky

Hlavní okno (QMainWindow) struktura:

Záložky (detailní obsah každé):

📊 AUDIT: Přehled statistik (počet jazyků, klíčů, problémů), Recent audits tabulka, Health status indikátor (zelená/žlutá/červená), Quick actions buttons (Run Audit, Export Report)

🌍 LANGUAGES: Tabulka všech jazyků (Flag | Code | Name | Total Keys | Missing | Extra | Duplicates | Completeness%), filtrovatelné, sortovatelné, per-language akce (Edit, Translate, Sync)

🔄 FALLBACK: CZ vs EN porovnání, seznam chybějících klíčů v CZ/EN, duplicity report (s počtem výskytů, řádky), Missing in code, Unused in code

📐 STRUCTURE: Pořadí klíčů, per-language seznam s problémy (chybějící # komentáře, whitespace issues, format errors), náhled řádků s chybou

🌐 TRANSLATION: Výběr target jazyka, provider selection, SmartTranslate checkbox, progress bar, tabulka kandidátů s scores (4-way), náhled, Apply button

✅ VALIDATION: Duplicity report, Placeholder issues lista, Format errors (lang_* struktura), Summary, Auto-fix s preview

📋 LOG: Real-time aktivitní záznam (text edit s timestamp), filtry (All/Info/Warning/Error), Clear/Save/Copy akce

Klávesové zkratky:

Datové formáty (.py vs .localize)

Formát #1: .py (Legacy Python dict)

Lokace: APP_DATA/localize_data.py

Příklad:

Výhody .py formátu:

• Nativní Python dict — bez parsing, přímé použití
• Historické (existující v projektu od začátku)
• Můžete přidat logiku/dynamiku (computed keys)

Nevýhody .py formátu:

• Syntaktická chyba = celý modul se nenahraje
• Složitější version control (diffs jsou veliké)
• Nebezpečné editovat bez IDE (Python syntax)

Formát #2: .localize (Nový textový formát — doporučený)

Lokace: APP_DATA/*.localize (např. lokalizedata.localize, mavi.localize)

Příklad:

Výhody .localize formátu:

• Textový, čitelný — snadné editovat
• INI-like struktura — parsuje se snadno
• Bezpečnější — syntax chyba nehorší (ignoruje se řádek)
• Git friendly — čisteší diffs
• Trans friendly — standard pro gettext-like nástroje

Nevýhody .localize formátu:

• Nový, méně zkušeností v projektu
• Parsing je nutný (malá overhead, ~ <10ms)

Konverze .py → .localize:

Reálné operační scénáře

Scénář 1: Přidání nového jazyka (Italština)

1. Otevřete aplikaci → jdete na [✅ LANGUAGES]
2. Klikněte [➕ Add Language]
3. Vyberte "🇮🇹 Italština (it)" z dropdown
4. Zaškrtněte [Auto-Translate using SmartTranslation]
5. Klikněte [Start] → system začíná překlad (4-way: CZ→IT + EN→IT s oběma providery)
6. Progress bar se pohybuje (0% → 50% → 100%)
7. Finish → tabulka s 450 kandidáty (každý s score 50-150)
8. Proveďte spot-check (zvolte 5-10 náhodných klíčů, ověřte kvalitu)
9. Klikněte [Apply] → uloží se do `APP_DATA/localize_data.py`
10. Commit: `git commit -m "Add Italian language (it) with auto-translations"`

Scénář 2: Update existující překladu (Němčina po změně CZ textu)

1. Před týdnem byl vytvořen překlad do Němčiny
2. Dnes se změní v CZ: "Ahoj" → "Vítejte"
3. Otevřete app → [🌍 LANGUAGES] → klikněte na DE → [Translate Changed Keys]
4. System detekuje: "msg_hello" se změnil (old: 'Ahoj', new: 'Vítejte')
5. SmartTranslate automaticky přeloží jen změněné klíče (zbývajících 449 bere z cache)
6. Překlad: "Vítejte" → "Willkommen" (score: 95)
7. Klikněte [Apply] → aktualizuje se pouze změ klíč v DE
8. Validace → ✅ vše OK
9. Commit: `git commit -m "Update German translation for msg_hello"`

Scénář 3: Oprava strukturálních problémů (Duplicity a chybějícíí emoji)

1. Audit detekuje: duplicita "msg_exit" (řádek 150 a 175), chybějící emoji v "lang_it"
2. Přejděte na [✅ VALIDATION] → vidíte seznam problémů
3. Zaškrtněte [Dry Run Mode] a klikněte [Auto-Fix All]
4. Preview: "Odstraní duplicitu (ponechá #1), přidá emoji 🇮🇹 k lang_it"
5. Zkontrolujete a klikněte [Apply] → skutečná oprava se provede
6. Backup vytvoří `backup_localize_data_2026-02-21_14-30-00.py`
7. Redo Audit → ✅ vše OK (0 problémů)
8. Commit: `git commit -m "Fix: Remove duplicates, add emoji to lang_it"`

Formáty dat

.py formát (Legacy):

.localize formát (Nový, textový, bezpečnější):

Podporované jazyky

60+ jazyků s kompletní metadata: ISO kódy, vlajky (emoji), nativní názvy, specifika.

Příklady: čeština (cs/cz), angličtina (en), němčina (de), francouzština (fr), španělština (es), ruština (ru), čínština (zh), japonština (ja), a další.

Troubleshooting & Řešení problémů

Problém: "Překlad selhává s chybou 'API limit exceeded'"

Příčina: Překladač dosáhl denního limitu (MyMemory 1000 slov/den, DeepL free 500k chars/měsíc).

Řešení:

1. Snižte v config.json (např. z 100 na 50)
2. Přepněte na jiného providera: (méně limitů)
3. Počkejte 24 hodin na reset déního limitu
4. Koupit si API klíč (DeepL Pro: €5+, Google Cloud: zdarma prvních 0.5M chars)

Problém: "Aplikace není reaguje / grafické rozhraní zamrzává"

Příčina: Operace běží na main threadu místo worker threadu.

Řešení:

1. Zavřete aplikaci: Ctrl+Q
2. Zkontrolujte pro error messages
3. Snižte batch_size (velké translationbatches zablokují UI)
4. Restartujte aplicaci s flagem pro verbózní output

Problém: "Jak přidat nový jazyk?"

Řešení (grafické rozhraní):

1. Klikněte na záložku [✅ LANGUAGES]
2. Klikněte [ ➕ Add Language]
3. Vyberte jazyk z dropdown (např. Italština)
4. Klikněte [Start Auto-Translate] → SmartTranslate přeloží všechny klíče
5. Review výsledky v tabulce (sort by score)
6. Klikněte [Apply] → uloží se do localize_data.py

Řešení (dávkový režim):

Problém: "Validace detekuje placeholdery chyby"

Příčina: Překlad zvětšil/zmenšil {var} placeholdery (např. {name} → {n}).

Řešení:

1. Přejděte na záložku [✅ VALIDATION]
2. Vidíte seznam "Placeholder Issues" s řádkům
3. Ručně opravte překlady v editor (změňte {n} zpět na {name})
4. Nebo klikněte [Auto-Fix Placeholders] (auto-replace)
5. Zaškrtněte [Dry-Run] pro preview před aplikací

Problém: "Smazal jsem omylem soubor — jak vrátit backup?"

Řešení:

1. Přejděte do adresáře
2. Najděte (s nejnovějším datumem)
3. Zkopírujte jej zpět na původní místo:
4. Klikněte [🔄 Audit] pro ověření, že se vrátilo vše

Problém: "Jak spustit dry-run mode (bez skutečných změn)?"

Řešení (grafické rozhraní):

1. Zaškrtněte checkbox [☐ Dry Run Mode] v horní liště
2. Spusťte jakoukoli operaci (Translate, Fix, atd.)
3. Vidíte preview co by se změnilo (bez skutečné úpravy)
4. Klikněte [Apply] pro skutečnou aplikaci (nebo [Cancel] pro zrušení)

Řešení (dávkový režim):

FAQ (Všechna časté otázky)

Q: Je LocalizeAdder bezpečný na produkci? Mohu ho spustit na 10,000+ klíčů?
A: Ano, zcela bezpečný. Všechny operace mají backup + dry-run mode + audit trail. Testuje se na 10,000+ klíčích bez problému.

Q: Jak rychle překládá? Jaká je typická doba pro 500 klíčů?
A: V průměru 100-200 klíčů/minutu (závislé na provideru). 500 klíčů = ~3-5 minut s Google Translatem, ~10 minut s DeepLem (kvůli quality scoringu).

Q: Můžu LocalizeAdder scriptnout/automatizovat v CI/CD?
A: Ano, fullCLI mode: , , . Podrobnosti viz. dávkový režim sekce.

Q: Jaké OS podporuje?
A: Python 3.7+ s PyQt5 → Windows 7+, Linux (Debian/Ubuntu), macOS 10.13+. Všechny stejnými."

Q: Jaký je doporučený workflow pro tým?
A: (1) Audit → detekce problémů, (2) Translate → přidá nové klíče do jazyků, (3) Validate → najde chyby, (4) Fix → opraví s backup, (5) Export → XLSX pro manual review, (6) Commit → do git.

Q: Existuje API pro programmatické použití (mimo grafická a dávková)?
A: Ano, můžete importovat moduly: . Podrobnosti v README.

Q: Kde jsou logy uloženy?
A: . Zadní 5 souborů se uchovává, starší se archivují.

Q: Jak mohu změnit téma z dark na light?
A: Config → → . Nebo v grafické rozhraní: ⚙️ Settings → UI Theme.