2026.06.04 frontend építés közben
This commit is contained in:
Roo
300
docs/v201/i18n_audit_backend_2026-04-13.md
Normal file
300
docs/v201/i18n_audit_backend_2026-04-13.md
Normal file
@@ -0,0 +1,300 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user