300 lines
11 KiB
Markdown
300 lines
11 KiB
Markdown
# 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. |