service-finder/docs/v201/i18n_audit_backend_2026-04-13.md

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)

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

   # 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

   # 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

// 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.