Μετάβαση στο περιεχόμενο

Διεθνοποίηση

Το Adaptive Learner διατίθεται σε 8 γλώσσες, όλες πλήρως μεταφρασμένες από v1.13.0 / Phase 26: DE, EN, ES, FR, EL, PT, TR, JA. Σύμφωνα με τον κανόνα έργου, το γερμανικό περιεχόμενο χρησιμοποιεί πραγματικά umlauts (ä, ö, ü, ß) — η ASCII-μετατραπείσα γερμανική είναι απαγορευμένη στο de.yaml και docs/help/de/**. Το test_i18n_translation_audit.py καρφώνει τόσο την κάλυψη umlaut όσο και το κατώφλι ≥90%-απόκλισης-από-EN για τους προηγουμένως passthrough καταλόγους.

Πού βρίσκονται τα strings

Backend

YAML κατάλογοι στο backend/config/i18n/{lang}.yaml — ένα αρχείο ανά γλώσσα. Ο κατάλογος αναφοράς είναι EN· κάθε άλλος κατάλογος πρέπει να έχει το ίδιο δέντρο κλειδιών.

# backend/config/i18n/en.yaml
common:
  save: Save
  cancel: Cancel
settings:
  title: Settings
  section_language: Language
  ...

Το backend εκθέτει GET /api/i18n/{lang} που επιστρέφει ολόκληρο τον κατάλογο ως JSON. Το hook useI18n του frontend το καλεί κατά την πρώτη απόδοση και αποθηκεύει το αποτέλεσμα.

Fallbacks frontend

Το frontend/src/i18n/fallbacks.ts φέρει ένα inline υποσύνολο strings σκληρά κωδικοποιημένο στο bundle frontend. Αυτά εμφανίζονται κατά την πρώτη απόδοση πριν φορτωθεί ο κατάλογος backend — και ως μόνιμη εναλλακτική αν το endpoint καταλόγου επιστρέψει 5xx.

Η αλυσίδα επίλυσης εναλλακτικής στο useI18n:

  1. Κατάλογος backend (live strings από /api/i18n/{lang}). Ακολούθησε διαδρομή dot-notation.
  2. Σκληρά κωδικοποιμένα fallbacks frontend (ανθεκτικότητα πρώτης απόδοσης).
  3. Fallback string του caller.
  4. Το ίδιο το κλειδί.

Βοήθεια in-app / docs site

Το docs/help/_meta.yaml δηλώνει το δέντρο πλοήγησης με τίτλους DE + EN ανά εγγραφή. Ο panel βοήθειας in-app το διαβάζει απευθείας· το scripts/generate_mkdocs_nav.py αναγεννά το μπλοκ nav του mkdocs.yml από την ίδια πηγή.

Το Markdown βοήθειας βρίσκεται στο docs/help/{lang}/... — ένας φάκελος ανά γλώσσα. Η λειτουργία docs_structure: folder του mkdocs-static-i18n χειρίζεται την επίλυση.

Προσθήκη νέας γλώσσας

  1. Κατάλογος backend: αντέγραψε backend/config/i18n/en.yaml σε backend/config/i18n/{newlang}.yaml. Μετέφρασε κάθε τιμή αυθεντικά (χωρίς EN-passthrough — το τεστ translation-audit θα αποτύχει με <90% απόκλιση). Στη συνέχεια τρέξε make sync-i18n για να αντικατοπτρίσεις τον κατάλογο στο frontend/src/data/i18n/{newlang}.json (το bundle λειτουργίας Dexie που το hotfix v1.16.0 έκανε ανθεκτικό στην πρώτη απόδοση).
  2. Frontend constants: πρόσθεσε τον κωδικό γλώσσας στο SUPPORTED_LANGUAGES στο frontend/src/lib/constants.ts.
  3. Frontend fallbacks: πρόσθεσε ένα μπλοκ {newlang}: {...} στο frontend/src/i18n/fallbacks.ts με το μικρό υποσύνολο strings που χρησιμοποιεί η διαδρομή κώδικα πρώτης απόδοσης.
  4. Ερωτήσεις αξιολόγησης: επεξεργάσου το plugins/adaptive-learner-plugin-assessment/adaptive_learner_assessment/questions.py — πρόσθεσε πεδίο text_{newlang} σε κάθε εγγραφή QUESTIONS και κάθε απάντηση. Επανεξήγαγε το JSON: poetry run python plugins/.../questions.py --export-json frontend/src/data/assessment-questions.json (δεν υπάρχει ακόμα τέτοιο CLI· το script στο scripts/ θα χρειαστεί μια μικρή προσθήκη).
  5. Session prompts: επεξεργάσου το plugins/adaptive-learner-plugin-session/adaptive_learner_session/prompts.py για να προσθέσεις ένα τρίτο κλειδί γλώσσας σε κάθε κελί (method, step). Επανεξήγαγε το JSON με τον ίδιο τρόπο.
  6. Docs site: ενημέρωσε το μπλοκ plugins.i18n.languages του mkdocs.yml και πρόσθεσε κατάλογο docs/help/{newlang}/ που αντικατοπτρίζει τη δομή EN.

Τεστ ισοτιμίας

Το backend/tests/test_i18n_parity.py διατρέχει κάθε κατάλογο και επαληθεύει ότι:

  • Κάθε γλώσσα έχει κάθε κλειδί που έχει η αναφορά (EN).
  • Καμία γλώσσα δεν έχει επιπλέον κλειδί που δεν έχει η αναφορά.

Αυτό πιάνει το πιο συνηθισμένο σφάλμα απόκλισης: κάποιος προσθέτει κλειδί στα EN και ξεχνά να το προσθέσει στα άλλα 7 αρχεία. Τρέξε make test-backend μετά από οποιαδήποτε αλλαγή καταλόγου.

Πληθυντικοί αριθμοί

Οι τρέχοντες κατάλογοι δεν χρησιμοποιούν σύνταξη πληθυντικών ICU. Τα λίγα counts που αποδίδουμε (αριθμός συνεδριών, ημέρες σερί) παίρνουν σκληρά κωδικοποιημένη επιλογή μορφής σε TS:

const label = count === 1 ? t("session_single") : t("session_plural");

Τα strings πληθυντικού ICU μέσω mkdocs-i18n ή runtime ICU library βρίσκονται στη λίστα αναβολών.

Γλώσσες RTL

Αραβικά, Εβραϊκά, Περσικά κ.λπ. θα χρειαστούν υποστήριξη διπλής κατεύθυνσης στο CSS. Το τρέχον θέμα υποθέτει LTR· η προσθήκη RTL βρίσκεται στη λίστα αναβολών.

Πότε ΝΑ ΜΗΝ προστεθεί string

Αν ένα string εμφανίζεται μόνο σε επιφάνειες για developers (μηνύματα σφαλμάτων που εκπέμπει η AdaptiveLearnerError, γραμμές log, δεδομένα fixture τεστ), άφησέ το στα Αγγλικά. Η μηχανή i18n είναι μόνο για strings ορατά από τελικούς χρήστες.

Οι κλήσεις console.warn και console.error του frontend παραμένουν επίσης Αγγλικά — είναι για developers που διαβάζουν την κονσόλα browser, όχι για τελικούς χρήστες.