OmniRoute/docs/i18n/sk/docs/I18N.md

i18n — Internationalization Guide (Slovenčina)

🌐 Languages: 🇺🇸 English · 🇪🇸 es · 🇫🇷 fr · 🇩🇪 de · 🇮🇹 it · 🇷🇺 ru · 🇨🇳 zh-CN · 🇯🇵 ja · 🇰🇷 ko · 🇸🇦 ar · 🇮🇳 hi · 🇮🇳 in · 🇹🇭 th · 🇻🇳 vi · 🇮🇩 id · 🇲🇾 ms · 🇳🇱 nl · 🇵🇱 pl · 🇸🇪 sv · 🇳🇴 no · 🇩🇰 da · 🇫🇮 fi · 🇵🇹 pt · 🇷🇴 ro · 🇭🇺 hu · 🇧🇬 bg · 🇸🇰 sk · 🇺🇦 uk-UA · 🇮🇱 he · 🇵🇭 phi · 🇧🇷 pt-BR · 🇨🇿 cs · 🇹🇷 tr

---

OmniRoute podporuje30 jazykovs úplným prekladom používateľského rozhrania dashboardu, preloženou dokumentáciou a podporou RTL pre arabčinu a hebrejčinu.## Quick Reference

Úloha	Príkaz
Generovať preklady	node scripts/i18n/generate-multilang.mjs messages
Preložiť dokumenty (LLM)	python3 scripts/i18n_autotranslate.py --api-url <url> --api-key <key> --model <model>
Overiť miestne nastavenie	python3 scripts/validate_translation.py quick -l cs
Skontrolujte kódové kľúče	python3 scripts/check_translations.py
Vygenerovať správu o kontrole kvality	skripty uzlov/i18n/generate-qa-checklist.mjs
Visual QA (dramatik)	skripty uzlov/i18n/run-visual-qa.mjs	## Architektúra

Source of Truth

-Reťazce používateľského rozhrania: src/i18n/messages/en.json (zdroj v angličtine, ~2800 kľúčov) -Súbory miestnych nastavení: src/i18n/messages/{locale}.json (30 prekladov) -Framework: next-intl s rozlíšením miestnych nastavení založených na súboroch cookie -Config: src/i18n/config.ts — definuje všetkých 30 miestnych nastavení, názvy jazykov, príznaky### Runtime Flow

1. Používateľ vyberie jazyk → súbor cookie „NEXT_LOCALE“.
2. src/i18n/request.ts rieši miestne nastavenie: cookie → hlavička Accept-Language → záložný en
3. Dynamický import načíta súbor messages/{locale}.json
4. Komponenty používajú useTranslations("namespace") a t("key")### Supported Locales

Kód	Jazyk	RTL	Kód prekladača Google
"ar"	العربية	áno	"ar"
bg	Български	Nie	bg
"cs"	Čeština	Nie	"cs"
"da"	Dansk	Nie	"da"
"de"	nemecky	Nie	"de"
"es"	Español	Nie	"es"
"fi"	Suomi	Nie	"fi"
"fr"	Français	Nie	"fr"
"on"	עברית	áno	"iw"
"ahoj"	हिन्दी	Nie	"ahoj"
"hu"	maďarčina	Nie	"hu"
'id'	Bahasa Indonézia	Nie	'id'
"to"	taliansky	Nie	"to"
"ja"	日本語	Nie	"ja"
"ko"	한국어	Nie	"ko"
ms	Bahasa Melayu	Nie	ms
nl	Holandsko	Nie	nl
"nie"	Norsk	Nie	"nie"
"phi"	filipínsky	Nie	tl
"pl"	Polski	Nie	"pl"
"pt"	Português (Portugalsko)	Nie	"pt"
"pt-BR"	Português (Brazília)	Nie	"pt"
"ro"	Română	Nie	"ro"
"ru"	Русский	Nie	"ru"
sk	slovenčina	Nie	sk
sv	Svenska	Nie	sv
'th'	ไทย	Nie	'th'
"tr"	Turecko	Nie	"tr"
„uk-UA“	Українська	Nie	"uk"
vi	Tiếng Việt	Nie	vi
"zh-CN"	中文 (简体)	Nie	"zh-CN"	## Adding a New Language

1. Register the Locale

Upravte src/i18n/config.ts:```ts // Add to LOCALES array "xx", // Add to LANGUAGES array { code: "xx", label: "XX", name: "Language Name", flag: "🏳️" },

### 2. Add to Generator

Upravte `scripts/i18n/generate-multilang.mjs` — pridajte záznam do `LOCALE_SPECS`:```js
{
  code: "xx",
  googleTl: "xx",
  label: "XX",
  flag: "🏳️",
  languageName: "Language Name",
  readmeName: "Language Name",
  docsName: "Language Name",
},

3. Generate Initial Translation

node scripts/i18n/generate-multilang.mjs messages

Tým sa vytvorí súbor src/i18n/messages/xx.json automaticky preložený z en.json cez Google Translate.### 4. Review & Fix Auto-Translations

Automatické preklady sú východiskovým bodom. Manuálne skontrolujte:

• Technická presnosť
• Kontextovo primeraná terminológia
• Správne zaobchádzanie so zástupnými symbolmi ({count}, {value} atď.)### 5. Validate

python3 scripts/validate_translation.py quick -l xx
python3 scripts/validate_translation.py diff common -l xx

6. Generate Translated Documentation

node scripts/i18n/generate-multilang.mjs docs

Auto-Translation Pipeline

generate-multilang.mjs (Google Translate)

Primárny nástroj automatického prekladu– používa bezplatné API služby Google Translate na generovanie prekladov pre reťazce používateľského rozhrania, súbory README a dokumentáciu.```bash node scripts/i18n/generate-multilang.mjs [messages|readme|docs|all]

| Režim | Čo to robí |
| ---------- | ----------------------------------------------------------------------------- |
| "správy" | Preloží chýbajúce kľúče v `src/i18n/messages/{locale}.json` z `en.json` |
| "readme" | Preloží `README.md` do všetkých miestnych nastavení ako `README.{code}.md` v koreňovom adresári projektu |
| "dokumenty" | Preloží `DOC_SOURCE_FILES` do `docs/i18n/{locale}/{docName}` |
| "všetky" | Spustí všetky tri režimy |

**Vlastnosti:**

-**Ochrana textu**: Maskuje bloky kódu (` ``` `), vložený kód (`` ` ``), odkazy/obrázky so značkami (`[text](url)`), značky HTML, tabuľky a zástupné symboly ICU (`{count}`, `{value}`, `{total}` atď.) pred prekladom a potom ich obnoví
-**Chunked batching**: Spája viacero reťazcov s oddeľovačmi `__OMNIROUTE_I18N_SEPARATOR__`, aby sa minimalizovali volania API (max. 1800 znakov na požiadavku)
-**Vyrovnávacia pamäť v pamäti**: Zabraňuje nadbytočným volaniam API pre opakované reťazce v rámci relácie
-**Logika opakovania**: Exponenciálne stiahnutie (až 5 pokusov s 300 ms × oneskorenie pokusu) pre chyby 429/5xx
-**Časový limit**: 20 sekúnd na požiadavku
-**Preskočiť existujúce**: Ak cieľový súbor už existuje, NIE JE prepísaný

**Dôležité správanie:**

- `docs/i18n/README.md` sa**regeneruje**pri každom spustení – je to automaticky generovaný index všetkých dokumentov
- Koreňové súbory `README.{code}.md` sa vytvoria iba vtedy, ak neexistujú (preskočí miestne nastavenia v `EXISTING_README_CODES`)
- Panely jazykov (`🌐**Jazyky:**...`) sa automaticky vkladajú/aktualizujú do všetkých preložených dokumentov### i18n_autotranslate.py (LLM-based)

**Sekundárny prekladač**– používa akékoľvek LLM API kompatibilné s OpenAI (vrátane samotného OmniRoute) na preklad existujúcich súborov `docs/i18n/`. Najlepšie na vylepšovanie alebo opätovné prekladanie dokumentov s lepšou kvalitou ako Google Translate.```bash
python3 scripts/i18n_autotranslate.py \
  --api-url http://localhost:20128/v1 \
  --api-key sk-your-key \
  --model gpt-4o

Vlastnosti:

• Skenuje súbory značiek docs/i18n/ pre anglické odseky
• Preskočí bloky kódu, tabuľky a už preložený obsah
• Odošle odseky do LLM s výzvou systému technického prekladu
• Podporuje všetkých 30 jazykov## Validation & QA

validate_translation.py

Validátor prekladu– porovnáva akékoľvek miestne nastavenie JSON s „en.json“ a hlási problémy.```bash

Quick check (counts only)

python3 scripts/validate_translation.py quick -l cs

Output:

Missing: 0

Untranslated: 0

Ignored (UNTRANSLATABLE_KEYS): 236

Detailed diff by category

python3 scripts/validate_translation.py diff common -l cs python3 scripts/validate_translation.py diff settings -l cs

Export to CSV

python3 scripts/validate_translation.py csv -l cs > report.csv

Export to Markdown

python3 scripts/validate_translation.py md -l cs > report.md

Full report (default)

python3 scripts/validate_translation.py -l cs

**Detekuje:**

-**Chýbajúce kľúče**– kľúče v súbore `en.json`, ale nie v súbore miestneho nastavenia
-**Extra keys**– kľúče v súbore miestneho nastavenia, ale nie v `en.json`
-**Nepreložené kľúče**– kľúče, kde sa miestne nastavenie rovná zdroju v angličtine (okrem zoznamu povolených)
-**Nesúlady zástupných symbolov**– Zástupné symboly JIS, ktoré sa nezhodujú medzi zdrojom a prekladom

**Výstupné kódy:**
| Kód | Význam |
|------|---------|
| 0 | OK |
| 1 | Všeobecná chyba |
| 2 | Chýbajúce reťazce (ťažká chyba) |
| 3 | Nepreložené varovanie (mäkké) |

**Prostredie:**Nastavte `TRANSLATION_LANG=cs` alebo použite príznak `-l cs`.### check_translations.py

**Kontrola kľúčov Code-to-JSON**– prehľadá `src/**/*.tsx` a `src/**/*.ts` kvôli volaniam `useTranslations()` a overí, či v `en.json` existujú všetky odkazované kľúče.```bash
# Basic check
python3 scripts/check_translations.py

# Verbose output
python3 scripts/check_translations.py --verbose

# Auto-fix (adds missing keys to en.json)
python3 scripts/check_translations.py --fix

generate-qa-checklist.mjs

Statická analýza QA– skenuje súbory stránok Next.js pre metriky rizika i18n a generuje správu Markdown.```bash node scripts/i18n/generate-qa-checklist.mjs

**Šeky:**

- Použitie triedy s pevnou šírkou (riziko pretečenia)
- Smerové triedy vľavo/vpravo (riziko RTL)
- Vzory náchylné na strihanie
- Parita miestnych nastavení (chýbajúce kľúče/kľúče navyše vs. en.json)
- Panely výberu jazyka README v prioritných miestnych nastaveniach (`es`, `fr`, `de`, `ja`, `ar`)

**Výstup:**`docs/reports/i18n-qa-checklist-{date}.md`### run-visual-qa.mjs

**Visual QA cez Playwright**– vytvára snímky obrazovky všetkých trás dashboardu vo viacerých lokalitách a oblastiach zobrazenia a potom vyhodnocuje stav stránky.```bash
# Default: es, fr, de, ja, ar on localhost:20128
node scripts/i18n/run-visual-qa.mjs

# Custom base URL and locales
QA_BASE_URL=http://staging.example.com QA_LOCALES=de,fr node scripts/i18n/run-visual-qa.mjs

# Custom routes
QA_ROUTES=/dashboard/settings,/dashboard/providers node scripts/i18n/run-visual-qa.mjs

Detekuje:

• Pretečenie textu
• Orezávanie prvkov
• Nezhody rozloženia RTL

Výstup:docs/reports/i18n-visual-qa-{date}.md + prehľad JSON## Managing Untranslatable Keys

untranslatable-keys.json

Súbor:scripts/i18n/untranslatable-keys.json

Zoznam povolených kľúčov, ktoré by mali zostať identické s anglickým zdrojom. Používa ho validate_translation.py, aby sa zabránilo falošne pozitívnym „nepreloženým“ upozorneniam.```json { "description": "Keys that should remain untranslated...", "keys": [ "common.model", "common.oauth", "health.cpu", ... ] }

**Čo sem patrí:**

- Názvy značiek/produktov: `landing.brandName`, `common.social-github`
– Technické výrazy/akronymy: `health.cpu`, `mcpDashboard.pid`, `settings.ai`
- ICU/formátové reťazce: `apiManager.modelsCount`, `health.milisecondsShort`
– zástupné hodnoty: `providers.openaiBaseUrlPlaceholder`, `cliTools.baseUrlPlaceholder`
- Názvy protokolov: `common.http`, `common.oauth`, `providers.oauth2Label`
- Sekcie navigácie: `sidebar.primarySection`, `sidebar.cliSection`

**Pridanie kľúča:**Upravte pole `keys` v `scripts/i18n/untranslatable-keys.json` a znova spustite overenie.## CI Integration

### GitHub Actions (`.github/workflows/ci.yml`)

CI kanál overuje všetky miestne nastavenia pri každom push a PR:

1. Úloha**`i18n-matrix`**– dynamicky zisťuje všetky súbory miestneho nastavenia (okrem `en.json`)
2. Úloha**`i18n`**– paralelne spustí `validate_translation.py quick -l '<lang>'` pre každé miestne nastavenie
3. Úloha**`ci-summary`**– agreguje výsledky do súhrnu dashboardu```yaml
# i18n-matrix: discovers languages
LANGS=$(ls src/i18n/messages/*.json | xargs -n1 basename | sed 's/.json$//' | grep -v '^en$')

# i18n: validates each language
python3 scripts/validate_translation.py quick -l '${{ matrix.lang }}'

Výstup na palubnej doske:```

🌍 Translations

Metric	Value
Languages checked	30
Total untranslated	0

✅ All translations complete

## File Structure

src/i18n/ ├── config.ts # Locale definitions (30 locales, RTL config) ├── request.ts # Runtime locale resolution └── messages/ ├── en.json # Source of truth (~2800 keys) ├── cs.json # Czech translation ├── de.json # German translation └── ... # 30 locale files total

scripts/ ├── i18n/ │ ├── generate-multilang.mjs # Auto-translation engine (Google Translate, 888 lines) │ ├── generate-qa-checklist.mjs # Static analysis QA │ ├── run-visual-qa.mjs # Playwright visual QA │ └── untranslatable-keys.json # Allowlist for validation (236 keys) ├── validate_translation.py # Translation validator ├── check_translations.py # Code-to-JSON key checker └── i18n_autotranslate.py # LLM-based doc translator

.github/workflows/ └── ci.yml # i18n validation in CI matrix

docs/ ├── I18N.md # This file — i18n toolchain documentation ├── i18n/ │ ├── README.md # Auto-generated language index │ ├── cs/ # Czech docs │ │ └── docs/ │ │ ├── I18N.md # Czech translation of this file │ │ └── ... │ ├── de/ # German docs │ └── ... # 30 locale directories └── reports/ ├── i18n-qa-checklist-.md # Static analysis reports └── i18n-visual-qa-.md # Visual QA reports

## Best Practices

### When Editing Translations

1.**Vždy najskôr upravte `en.json`**– je to zdroj pravdy
2.**Spustite `generate-multilang.mjs messages`**na šírenie nových kľúčov do všetkých miestnych nastavení
3.**Skontrolujte automatické preklady**– Prekladač Google je východiskovým bodom, nie konečným
4.**Overiť pred potvrdením**— `python3 scripts/validate_translation.py quick -l <lang>`
5.**Aktualizujte súbor `untranslatable-keys.json`**, ak má kľúč zostať v angličtine### Placeholder Safety

- Zástupné symboly ICU (`{count}`, `{value}`, `{total}`, `{seconds}`) musia byť zachované presne
- Formáty v množnom čísle (`{count, plural, one {# model} other {# models}}`) si musia zachovať štruktúru
- Validátor automaticky zistí nesúlad zástupných symbolov### Adding New Translation Keys in Code

```tsx
// Use namespaced keys
const t = useTranslations("settings");
t("cacheSettings"); // maps to settings.cacheSettings in JSON

// Run check_translations.py to verify keys exist
python3 scripts/check_translations.py --verbose

RTL Considerations

• Arabčina (ar) a hebrejčina (he) sú RTL miestne nastavenia – Vyhnite sa pevne zakódovaným CSS „vľavo“/„vpravo“ – použite logické vlastnosti „začiatok/koniec“
• Visual QA zachytáva nesúlad rozloženia RTL prostredníctvom run-visual-qa.mjs## Known Issues & History

in.json → hi.json Fix

Generátor pôvodne používal pre hindčinu „code: „in“ (zastaraný kód Prekladača Google) namiesto správneho „hi“ podľa normy ISO 639-1. Tým sa vytvoril osirelý duplikát súboru „in.json“ súboru „hi.json“. Opravené zmenou code: "in" na code: "hi" v generate-multilang.mjs a odstránením osirelého súboru.### docs/i18n/README.md Is Auto-Generated

Súbor docs/i18n/README.md úplne vygeneruje generate-multilang.mjs docs. Všetky manuálne úpravy sa stratia. Použite docs/I18N.md (tento súbor) pre ručne napísanú dokumentáciu, ktorá by mala pretrvávať.### External Untranslatable Keys List

Zoznam povolených kľúčov „untranslatable-keys.json“ bol pre jednoduchšiu údržbu presunutý z vloženého Pythonu nastaveného v súbore „validate_translation.py“ do externého súboru JSON. Validátor ho načíta za behu.### generate-multilang.mjs Hindi Code Fix

Generátor pôvodne používal pre hindčinu „code: „in“ (zastaraný kód Prekladača Google) namiesto správneho „hi“ podľa normy ISO 639-1. Toto bolo zavedené v upstreamovom potvrdení 952b0b22c od diegosouzapw. Opravené zmenou code: "in" na code: "hi" v poli LOCALE_SPECS a odstránením osirelého súboru in.json.### validate_translation.py Ignored Count Output

"Rýchla" kontrola teraz zobrazuje počet ignorovaných kľúčov z "untranslatable-keys.json":``` Missing: 0 Untranslated: 0 Ignored (UNTRANSLATABLE_KEYS): 236