OmniRoute/docs/i18n/pl/docs/I18N.md

i18n — Internationalization Guide (Polski)

🌐 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 obsługuje30 językówz pełnym tłumaczeniem interfejsu użytkownika pulpitu nawigacyjnego, przetłumaczoną dokumentacją i obsługą RTL dla języka arabskiego i hebrajskiego.## Quick Reference

Zadanie	Polecenie
Generuj tłumaczenia	node scripts/i18n/generate-multilang.mjs wiadomości
Tłumaczenie dokumentów (LLM)	python3 scripts/i18n_autotranslate.py --api-url <url> --api-key <klucz> --model <model>
Sprawdź ustawienia regionalne	python3 scripts/validate_translation.py szybkie -l cs
Sprawdź klucze kodu	skrypty Python3/check_translations.py
Wygeneruj raport kontroli jakości	skrypty węzła/i18n/generate-qa-checklist.mjs
Kontrola jakości wizualnej (dramaturg)	skrypty węzła/i18n/run-visual-qa.mjs	## Architektura

Source of Truth

-Ciągi interfejsu użytkownika: src/i18n/messages/en.json (źródło angielskie, ~2800 kluczy) -Pliki regionalne: src/i18n/messages/{locale}.json (30 tłumaczeń) -Framework: next-intl z rozpoznawaniem ustawień regionalnych na podstawie plików cookie -Config: src/i18n/config.ts — definiuje wszystkie 30 ustawień regionalnych, nazw języków, flag### Runtime Flow

1. Użytkownik wybiera język → Zestaw plików cookie NEXT_LOCALE
2. src/i18n/request.ts rozwiązuje ustawienia regionalne: plik cookie → nagłówek Accept-Language → rezerwa en
3. Import dynamiczny ładuje messages/{locale}.json
4. Komponenty używają useTranslations("przestrzeń nazw") i t("klucz")### Supported Locales

Kod	Język	RTL	Kod Tłumacza Google
ar	العربية	Tak	ar
bg	Български	Nie	bg
cs	Cesztina	Nie	cs
da	Dansk	Nie	da
de	niemiecki	Nie	de
es	hiszpański	Nie	es
fi	Suomi	Nie	fi
fr	Français	Nie	fr
on	עברית	Tak	iw
cześć	हिन्दी	Nie	cześć
hu	Madziar	Nie	hu
id	Bahasa Indonezja	Nie	id
to	włoski	Nie	to
ja	日本語	Nie	ja
ko	한국어	Nie	ko
ms	Bahasa Melayu	Nie	ms
nl	Holandia	Nie	nl
nie	Norsk	Nie	nie
fi	filipiński	Nie	tl
pl	Polski	Nie	pl
pt	Português (Portugalia)	Nie	pt
pt-BR	Português (Brazylia)	Nie	pt
ro	Roman	Nie	ro
ru	Rosyjski	Nie	ru
sk	Słowenia	Nie	sk
sv	Szweńska	Nie	sv
t	ไทย	Nie	t
tr	turecki	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

Edytuj 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

Edytuj `scripts/i18n/generate-multilang.mjs` — dodaj wpis 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

Spowoduje to utworzenie pliku src/i18n/messages/xx.json przetłumaczonego automatycznie z en.json za pomocą Tłumacza Google.### 4. Review & Fix Auto-Translations

Automatyczne tłumaczenia to punkt wyjścia. Sprawdź ręcznie dla:

• Dokładność techniczna
• Terminologia dostosowana do kontekstu
• Właściwa obsługa symboli zastępczych ({count}, {value} itp.)### 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)

Główny silnik automatycznego tłumaczenia— korzysta z bezpłatnego interfejsu API Tłumacza Google do generowania tłumaczeń ciągów interfejsu użytkownika, plików README i dokumentacji.```bash node scripts/i18n/generate-multilang.mjs [messages|readme|docs|all]

| Tryb | Co to robi |
| ---------- | ---------------------------------------------------------------------------------------- |
| `wiadomości` | Tłumaczy brakujące klucze w `src/i18n/messages/{locale}.json` z `en.json` |
| „czytaj” | Tłumaczy `README.md` na wszystkie ustawienia regionalne jako `README.{code}.md` w katalogu głównym projektu |
| `dokumenty` | Tłumaczy `DOC_SOURCE_FILES` na `docs/i18n/{locale}/{docName}` |
| „wszyscy” | Uruchamia wszystkie trzy tryby |

**Cechy:**

-**Ochrona tekstu**: Maskuje bloki kodu (` ``` `), kod wbudowany (`` ` ``), linki/obrazy przeceny (`[text](url)`), znaczniki HTML, tabele i obiekty zastępcze ICU (`{count}`, `{value}`, `{total}` itp.) przed tłumaczeniem, a następnie przywraca je
-**Porcjowane wsadowanie**: Łączy wiele ciągów za pomocą ograniczników `__OMNIROUTE_I18N_SEPARATOR__`, aby zminimalizować wywołania API (maks. 1800 znaków na żądanie)
-**Pamięć podręczna w pamięci**: pozwala uniknąć zbędnych wywołań API dla powtarzających się ciągów w ramach sesji
-**Logika ponawiania prób**: Wykładnicze wycofywanie (do 5 prób z opóźnieniem 300 ms × próba) w przypadku błędów 429/5xx
-**Timeout**: 20 seconds per request
-**Pomiń istniejące**: Jeśli plik docelowy już istnieje, NIE zostanie nadpisany

**Ważne zachowania:**

- `docs/i18n/README.md` jest**regenerowany**przy każdym uruchomieniu — jest to automatycznie generowany indeks wszystkich dokumentów
- Pliki główne `README.{code}.md` są tworzone tylko wtedy, gdy nie istnieją (pomijają ustawienia regionalne w `EXISTING_README_CODES`)
- Paski językowe (`🌐**Języki:**...`) są automatycznie wstawiane/aktualizowane we wszystkich przetłumaczonych dokumentach### i18n_autotranslate.py (LLM-based)

**Dodatkowy tłumacz**— używa dowolnego API LLM kompatybilnego z OpenAI (w tym samego OmniRoute) do tłumaczenia istniejących plików przecen `docs/i18n/`. Najlepsze do polerowania lub ponownego tłumaczenia dokumentów w lepszej jakości niż Tłumacz Google.```bash
python3 scripts/i18n_autotranslate.py \
  --api-url http://localhost:20128/v1 \
  --api-key sk-your-key \
  --model gpt-4o

Cechy:

• Skanuje pliki przecen docs/i18n/ w poszukiwaniu akapitów w języku angielskim
• Pomija bloki kodu, tabele i już przetłumaczoną treść
• Wysyła akapity do LLM z monitem systemu tłumaczeń technicznych
• Obsługuje wszystkie 30 języków## Validation & QA

validate_translation.py

Weryfikator tłumaczeń— porównuje dowolne ustawienia regionalne JSON z en.json i zgłasza problemy.```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

**Wykrywa:**

-**Brakujące klucze**— klucze w `en.json`, ale nie w pliku ustawień regionalnych
-**Dodatkowe klucze**— klucze w pliku ustawień regionalnych, ale nie w `en.json`
-**Nieprzetłumaczone klucze**— klucze, w których wartość regionalna jest równa źródłu w języku angielskim (z wyłączeniem listy dozwolonych)
-**Niedopasowania symboli zastępczych**— symbole zastępcze ICU, które nie pasują między źródłem a tłumaczeniem

**Kody wyjścia:**
| Kod | Znaczenie |
|------|-------------|
| 0 | OK |
| 1 | Błąd ogólny |
| 2 | Brakujące ciągi znaków (błąd twardy) |
| 3 | Nieprzetłumaczone ostrzeżenie (miękkie) |

**Środowisko:**Ustaw `TRANSLATION_LANG=cs` lub użyj flagi `-l cs`.### check_translations.py

**Kontrola klucza Code-to-JSON**— skanuje pliki `src/**/*.tsx` i `src/**/*.ts` w poszukiwaniu wywołań `useTranslations()` i sprawdza, czy wszystkie przywoływane klucze istnieją w `en.json`.```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

Analiza statyczna QA— skanuje pliki strony Next.js pod kątem wskaźników ryzyka i18n i generuje raport Markdown.```bash node scripts/i18n/generate-qa-checklist.mjs

**Kontrole:**

- Użycie klasy o stałej szerokości (ryzyko przepełnienia)
- Klasy kierunkowe lewo/prawo (ryzyko RTL)
- Wzory podatne na przycinanie
- Parzystość ustawień regionalnych (brakujące/dodatkowe klucze vs `en.json`)
- Paski wyboru języka README w ustawieniach priorytetowych (`es`, `fr`, `de`, `ja`, `ar`)

**Wyjście:**`docs/reports/i18n-qa-checklist-{data}.md`### run-visual-qa.mjs

**Wizualna kontrola jakości za pośrednictwem Playwright**— wykonuje zrzuty ekranu wszystkich tras pulpitu nawigacyjnego w wielu lokalizacjach i rzutniach, a następnie ocenia stan strony.```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

Wykrywa:

• Przepełnienie tekstu
• Przycinanie elementów
• Niezgodność układu RTL

Wyjście:docs/reports/i18n-visual-qa-{date}.md + raport JSON## Managing Untranslatable Keys

untranslatable-keys.json

Plik:scripts/i18n/untranslatable-keys.json

Lista dozwolonych kluczy, które powinny pozostać identyczne z kluczami źródłowymi w języku angielskim. Używane przez validate_translation.py w celu uniknięcia fałszywie pozytywnych ostrzeżeń o „nieprzetłumaczonych”.```json { "description": "Keys that should remain untranslated...", "keys": [ "common.model", "common.oauth", "health.cpu", ... ] }

**Co tu należy:**

- Nazwy marek/produktów: `landing.brandName`, `common.social-github`
- Terminy techniczne/akronimy: `health.cpu`, `mcpDashboard.pid`, `settings.ai`
- Ciągi ICU/format: `apiManager.modelsCount`, `health.millisekundyShort`
- Wartości zastępcze: `providers.openaiBaseUrlPlaceholder`, `cliTools.baseUrlPlaceholder`
- Nazwy protokołów: `common.http`, `common.oauth`, `providers.oauth2Label`
- Sekcje nawigacyjne: `sidebar.primarySection`, `sidebar.cliSection`

**Aby dodać klucz:**Edytuj tablicę `keys` w pliku `scripts/i18n/untranslatable-keys.json` i ponownie uruchom weryfikację.## CI Integration

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

Potok CI sprawdza wszystkie ustawienia regionalne przy każdym naciśnięciu i PR:

1.**`Zadanie i18n-matrix`**— dynamicznie odkrywa wszystkie pliki locale (z wyjątkiem `en.json`)
2.**``i18n` job**— uruchamia `validate_translation.py Quick -l '<lang>'` równolegle dla każdego ustawienia regionalnego
3.**Zadanie „ci-summary”**— agreguje wyniki w podsumowanie 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 }}'

Wyjście panelu:```

🌍 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.**Zawsze najpierw edytuj `en.json`**— to źródło prawdy
2.**Uruchom `generate-multilang.mjs Messages`**, aby rozpropagować nowe klucze do wszystkich lokalizacji
3.**Sprawdź automatyczne tłumaczenia**— Tłumacz Google to punkt wyjścia, a nie ostateczny
4.**Sprawdź poprawność przed zatwierdzeniem**— `python3 scripts/validate_translation.py szybkie -l <język>`
5.**Zaktualizuj `untranslatable-keys.json`**jeśli klucz ma pozostać w języku angielskim### Placeholder Safety

- Elementy zastępcze ICU (`{count}`, `{value}`, `{total}`, `{sekundy}`) muszą być dokładnie zachowane
- Formaty liczby mnogiej (`{count, plural, one {# model} other {# modele}}`) muszą zachować strukturę
- Walidator automatycznie wykrywa niedopasowania symboli zastępczych### 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

• Arabski („ar”) i hebrajski („he”) to języki RTL
• Unikaj zakodowanych na stałe CSS „left”/right — używaj właściwości logicznych start/end
• Visual QA wychwytuje niezgodności układu RTL za pomocą pliku run-visual-qa.mjs## Known Issues & History

in.json → hi.json Fix

Generator pierwotnie używał code: „in” (przestarzały kod Tłumacza Google) dla języka hindi zamiast prawidłowego hi ISO 639-1. Spowodowało to utworzenie osieroconego duplikatu in.json hi.json. Naprawiono poprzez zmianę code: "in" na code: "hi" w generate-multilang.mjs i usunięcie osieroconego pliku.### docs/i18n/README.md Is Auto-Generated

Plik docs/i18n/README.md jest całkowicie regenerowany przez generate-multilang.mjs docs. Wszelkie ręczne zmiany zostaną utracone. Użyj docs/I18N.md (tego pliku), aby uzyskać odręczną dokumentację, która powinna zostać zachowana.### External Untranslatable Keys List

Lista dozwolonych plików „untranslatable-keys.json” została przeniesiona z wbudowanego zestawu Pythona w pliku „validate_translation.py” do zewnętrznego pliku JSON, aby ułatwić konserwację. Walidator ładuje go w czasie wykonywania.### generate-multilang.mjs Hindi Code Fix

Generator pierwotnie używał code: „in” (przestarzały kod Tłumacza Google) dla języka hindi zamiast prawidłowego hi ISO 639-1. Zostało to wprowadzone w poprzednim zatwierdzeniu 952b0b22c przez diegosouzapw. Naprawiono poprzez zmianę code: "in" na code: "hi" w tablicy LOCALE_SPECS i usunięcie osieroconego pliku in.json.### validate_translation.py Ignored Count Output

„Szybkie” sprawdzenie wyświetla teraz liczbę zignorowanych kluczy z pliku „untranslatable-keys.json”:``` Missing: 0 Untranslated: 0 Ignored (UNTRANSLATABLE_KEYS): 236