# Service Finder Backend i18n Audit Report

**Dátum:** 2026-04-14  
**Audit célja:** A backend forráskód internacionalizációs (i18n) felkészültségének elemzése  
**Auditált könyvtár:** `/opt/docker/dev/service_finder/backend/app`

## 1. Nyelvfelismerés és Middleware

### 1.1 HTTP Fejlécek és Query Paraméterek
A rendszer **NEM tartalmaz dedikált middleware-t** a nyelvfelismeréshez. A `main.py` fájlban nincs olyan middleware, amely kezelné az `Accept-Language` HTTP fejlécet vagy nyelvi query paramétereket.

### 1.2 Felhasználói Profil Alapú Nyelvfelismerés
A rendszer támogatja a felhasználói profilban tárolt nyelvi preferenciákat:
- A `UserLiteRegister` séma tartalmaz `lang` mezőt (alapértelmezett: "hu")
- A `UserKYCComplete` séma tartalmaz `preferred_language` mezőt (alapértelmezett: "hu")
- A felhasználói adatbázisban a nyelvi preferencia tárolható, de **nincs automatikus middleware**, amely ezt a beállítást alkalmazná a kérések során

### 1.3 Nyelvfelismerési Megközelítés
A nyelvfelismerés jelenleg **explicit paraméterátadáson** alapul:
- A `TranslationService.get_text()` metódus `lang` paramétert vár
- A `LocaleManager.get()` metódus `lang` paramétert vár
- A frontendnek explicit módon kell átadnia a nyelvi preferenciát

## 2. Fordítási Rendszer és String Kezelés

### 2.1 Fordítási Szolgáltatás (`translation_service.py`)
A rendszer tartalmaz egy teljes értékű fordítási szolgáltatást:

**Főbb jellemzők:**
- Memória-cache a gyors hozzáféréshez
- Fallback logika (hu → en → kulcs visszaadása)
- Változó behelyettesítés támogatása (`{{name}}` szintaxis)
- Hierarchikus kulcsok támogatása (`AUTH.LOGIN.TITLE`)
- JSON export a frontend számára

**Adatbázis integráció:**
- `system.translations` tábla a fordítások tárolására
- `is_published` mező a publikációs állapot kezelésére
- Dinamikus cache frissítés

### 2.2 Locale Manager (`i18n.py`)
Egyszerűsített JSON-alapú locale kezelő:
- Statikus JSON fájlok betöltése
- Hierarchikus kulcsok kezelése
- Rövid alias (`t`) a könnyű használathoz

### 2.3 Hardcoded Stringek
Az audit során a következő típusú hardcoded stringeket azonosítottam:

**Hibaüzenetek (deps.py):**
- "Érvénytelen vagy lejárt munkamenet."
- "Token azonosítási hiba."
- "A felhasználó nem található."
- "A művelethez aktív profil és KYC azonosítás szükséges."
- "Nincs jogosultsága ehhez az erőforráshoz."

**Auth végpont (auth.py):**
- "Hibás adatok."
- "Regisztráció sikeres. Aktivációs e-mail elküldve."
- "Email sikeresen megerősítve."

**Megfigyelés:** A hardcoded stringek **kizárólag magyar nyelven** vannak, ami korlátozza a többnyelvűséget.

## 3. Adatbázis Séma és Modellek

### 3.1 Translation Modell (`system.translation`)
```python
class Translation(Base):
    __tablename__ = "translations"
    __table_args__ = {"schema": "system"}
    
    id: Mapped[int]
    key: Mapped[str]        # Fordítási kulcs
    lang: Mapped[str]       # Nyelvi kód (hu, en, de)
    value: Mapped[str]      # Fordított szöveg
    is_published: Mapped[bool]  # Publikációs állapot
```

**Erősségek:**
- Dedikált tábla a fordításoknak
- Nyelvi kód indexelése
- Publikációs állapot kezelése

**Gyengeségek:**
- Nincs versioning vagy audit trail
- Nincs szerző/felelős mező
- Nincs kategóriázás vagy csoportosítás

### 3.2 Egyéb Modellek Többnyelvűsége
A többi modell (pl. `VehicleModelDefinition`, `VehicleType`, `FeatureDefinition`) **NEM tartalmaz többnyelvű mezőket**:
- Minden szöveges mező egyetlen nyelven tárolódik
- Nincs JSONB mező fordításokhoz
- Nincs kapcsolt fordítási tábla

**Kivétel:** A `marketing_name_aliases` JSONB mező tartalmazhat alternatív neveket, de ez nem nyelvi fordítás, hanem marketing alias.

## 4. Pydantic Sémák és Validáció

### 4.1 Nyelvi Beállítások a Sémákban
- `UserLiteRegister`: `lang` mező (alapértelmezett: "hu")
- `UserKYCComplete`: `preferred_language` mező (alapértelmezett: "hu")
- `preferred_currency` mező a pénznem preferenciákhoz

### 4.2 Hibaüzenetek Validációban
A Pydantic sémák **nem használják a fordítási rendszert** a validációs hibaüzenetekhez:
- `Field(..., description="Minimum 8 karakter hosszú jelszó")` - magyar hardcoded
- `Field(..., pattern=r"^\+?[0-9]{7,15}$")` - nincs lokalizált hibaüzenet

## 5. Fájlstruktúra és Locales

### 5.1 Könyvtárszerkezet
```
backend/app/
├── locales/
│   └── hu.json          # Magyar fordítások
├── core/
│   └── i18n.py          # Locale manager
├── services/
│   └── translation_service.py  # Fordítási szolgáltatás
└── static/locales/      # Frontend számára exportált JSON-ok
```

### 5.2 Locales Tartalom (`hu.json`)
A `hu.json` fájl jelenlegi tartalma:
- Email sablonok (regisztráció, jelszó visszaállítás)
- Közös UI elemek (SAVE, CANCEL, DELETE)
- Jármű kapcsolatos szövegek
- Költség kapcsolatos szövegek

**Hiányosságok:**
- Csak magyar nyelvű fordítások
- Nincs angol (`en.json`) vagy más nyelvi fájl
- Korlátozott számú fordítási kulcs (~20 kulcs)

## 6. API Végpontok

### 6.1 Nyilvános i18n API (`translations.py`)
**Végpontok:**
- `GET /api/v1/translations/{lang}` - Teljes fordításcsomag
- `GET /api/v1/translations/{lang}/{key:path}` - Specifikus kulcs

**Jellemzők:**
- Nincs autentikáció szükséges
- Fallback angol nyelvre
- Hierarchikus kulcsok támogatása

### 6.2 Egyéb Végpontok i18n Használata
A többi API végpont **NEM használja a fordítási rendszert**:
- Minden válasz és hibaüzenet magyar nyelven
- Nincs nyelvi paraméter átadása
- Nincs automatikus nyelvfelismerés

## 7. i18n Readiness Értékelés (1-10 skála)

### 7.1 Összesített Pontszám: **4/10**

**Alapok (3/5):**
- ✅ Fordítási tábla az adatbázisban
- ✅ Fordítási szolgáltatás implementálva
- ✅ Locale manager implementálva
- ✅ API végpont a fordításokhoz
- ❌ Hiányzik a nyelvfelismerési middleware

**String Kezelés (2/5):**
- ✅ Hierarchikus kulcsok támogatása
- ✅ Változó behelyettesítés
- ✅ Fallback logika
- ❌ Hardcoded stringek a kódban
- ❌ Nem használják a végpontok a fordítási rendszert

**Adatbázis Támogatás (1/5):**
- ✅ Alap Translation modell
- ❌ Nincs többnyelvű mező támogatás
- ❌ Nincs JSONB fordítási mező
- ❌ Nincs kapcsolt fordítási tábla
- ❌ Nincs tartalom versioning

**Frontend Integráció (3/5):**
- ✅ JSON export a frontend számára
- ✅ Nyilvános API végpont
- ✅ Hierarchikus struktúra
- ❌ Csak magyar nyelvű fordítások
- ❌ Korlátozott számú fordítási kulcs

## 8. Javaslatok a Fejlesztéshez

### 8.1 Azonnali Műveletek (Magas Prioritás)

1. **Nyelvfelismerési Middleware Implementálása**
   ```python
   # Példa middleware a nyelvfelismeréshez
   class LocaleMiddleware:
       async def __call__(self, request: Request, call_next):
           # 1. Query paraméter: ?lang=hu
           # 2. Accept-Language header
           # 3. Felhasználói profil
           # 4. Alapértelmezett (hu)
           request.state.locale = determine_locale(request)
           return await call_next(request)
   ```

2. **Hardcoded Stringek Migrálása**
   - Azonosítsd az összes hardcoded stringet a kódban
   - Hozd létre a megfelelő fordítási kulcsokat
   - Cseréld le a `translation_service.get_text()` hívásokra

3. **Angol Fordítások Hozzáadása**
   - Hozd létre az `en.json` fájlt
   - Fordítsd le a meglévő magyar szövegeket
   - Bővítsd a fordítási kulcsokat

### 8.2 Középtávú Fejlesztések (Közepes Prioritás)

4. **Többnyelvű Adatbázis Mezők**
   ```python
   # JSONB mező fordításokhoz
   class VehicleType(Base):
       name_translations: Mapped[dict] = mapped_column(JSONB, default={})
       
   # Vagy kapcsolt fordítási tábla
   class VehicleTypeTranslation(Base):
       vehicle_type_id: Mapped[int]
       lang: Mapped[str]
       name: Mapped[str]
   ```

5. **Pydantic Séma Integráció**
   - Lokalizált validációs hibaüzenetek
   - Automatikus nyelvfelismerés a sémákban
   - Dinamikus field description-ök

6. **Fordítási Admin Felület**
   - CRUD műveletek a fordításokhoz
   - Bulk import/export
   - Fordítási állapot követés

### 8.3 Hosszútávú Fejlesztések (Alacsony Prioritás)

7. **Fordítási Verziókezelés**
   - Audit trail a változtatásokhoz
   - Versioning a fordításokhoz
   - Rollback lehetőség

8. **Automatikus Fordítás Integráció**
   - DeepL/Google Translate API integráció
   - Fordítási javaslatok
   - Minőségellenőrzés

9. **Nyelvi Csomagok Kezelése**
   - Moduláris nyelvi csomagok
   - Community fordítások
   - Nyelvi variánsok (pl. hu-HU, hu-RO)

## 9. Technikai Specifikációk a Frontend Integrációhoz

### 9.1 Nyelvi Paraméter Átadása
A frontendnek a következő módokon kell átadnia a nyelvi preferenciát:

1. **Query Paraméter:** `?lang=hu`
2. **HTTP Fejléc:** `Accept-Language: hu,en;q=0.9`
3. **JWT Token:** Nyelvi preferencia a token payload-ban
4. **API Végpontok:** Explicit `lang` paraméter

### 9.2 Fordítási API Használata
```javascript
// 1. Teljes fordításcsomag letöltése
fetch('/api/v1/translations/hu')

// 2. Specifikus kulcs lekérése
fetch('/api/v1/translations/hu/AUTH.LOGIN.TITLE')

// 3. Fallback logika a frontenden
async function getTranslation(key, lang = 'hu') {
    try {
        const response = await fetch(`/api/v1/translations/${lang}/${key}`);
        return await response.json();
    } catch {
        // Fallback angolra
        const response = await fetch(`/api/v1/translations/en/${key}`);
        return await response.json();
    }
}
```

### 9.3 Cache Stratégia
- **Szerveroldali:** Memória cache a `TranslationService`-ben
- **Kliensoldali:** LocalStorage vagy Service Worker cache
- **CDN:** Statikus JSON fájlok CDN-en keresztül

## 10. Következő Lépések

1. **Prioritás 1:** Middleware implementálása a nyelvfelismeréshez
2. **Prioritás 2:** Hardcoded stringek migrálása a fordítási rendszerbe
3. **Prioritás 3:** Angol fordítások hozzáadása
4. **Prioritás 4:** API végpontok frissítése a nyelvi paraméter támogatásához
5. **Prioritás 5:** Frontend dokumentáció a nyelvi integrációhoz

---

**Összefoglalás:** A Service Finder backend rendelkezik egy jól felépített fordítási infrastruktúrával, de az implementáció hiányos. A rendszer képes tárolni és kiszolgálni a fordításokat, de a tényleges használat korlátozott. A legnagyobb hiányosság a nyelvfelismerés hiánya és a hardcoded stringek dominanciája. A javasolt fejlesztések megvalósításával a rendszer teljes értékű többnyelvű támogatást nyújthat a frontend számára.