Repository navigation
UC‐07
| Field | Details |
|---|---|
| Use Case ID | UC-07 |
| Use Case Name | Auto-translate POI Content |
| Primary Actor | System (Automated Event) |
| Secondary / System Actors | External Translation API (Deep-translator / Google Translate API), Centralized Database |
| Maturity | Focused |
| Author(s) | @Phatnguyen3003 |
| Date | September 21, 2026 |
- Summary: The system automatically translates the primary text description of a Point of Interest (POI) into all configured target languages using an external translation service and stores the localized text in the database.
- Triggers: Automated background event triggered by UC-04 (Manage Exhibits / POIs) whenever a new POI is created or an existing POI's primary description is modified.
-
Preconditions:
- UC-04 has successfully saved/updated the primary POI text in the database.
- Target language list (e.g., English, Japanese, Korean, Chinese) is configured in system environment settings.
-
Postconditions:
- Localized text descriptions for all target languages are stored in the database mapped to the POI ID.
- Trigger event is dispatched to UC-09: Auto-generate & Cache Audio Files for the translated text.
| Step | Actor / System Action | System Response |
|---|---|---|
| 1 | System receives background trigger event from UC-04 containing POI ID, Title, and Primary Text (Vietnamese). | — |
| 2 | — | Retrieve system target language configuration list (e.g., ['en', 'ja', 'ko', 'zh']). |
| 3 | — | Iterate through target languages and construct translation payload for each target language code. |
| 4 | System sends asynchronous API requests containing primary text to External Translation API. | — |
| 5 | External Translation API processes text and returns localized strings for each target language. | — |
| 6 | — | Validate API response (checks for non-empty text strings and valid response codes). [E1]
|
| 7 | — | Write/Update localized POI text entries in the Centralized Database (mapped by POI ID and Language Code). |
| 8 | — | Automatically trigger UC-09: Auto-generate & Cache Audio Files with the newly translated POI content. |
| 9 | — | Log success event in System Log and set POI translation status flag to COMPLETED. Use case ends. |
- A1.1: Translation for a specific target language fails due to transient network error while other languages succeed.
- A1.2: System retries translation request for the failed language up to 3 times with exponential backoff.
- A1.3: If retry succeeds, system proceeds to Step 7 of Main Event.
-
A1.4: If retry fails after max attempts, system stores successful translations in Database, flags POI status as
PARTIAL_TRANSLATION_FAILED, and logs error details for Admin review.
-
Trigger: API returns HTTP errors (e.g.,
429 Too Many Requests,503 Service Unavailable) or request times out. -
System Behavior:
- System catches exception and logs failure stack trace.
- System updates POI translation status flag in Database to
TRANSLATION_FAILED. - System skips triggering UC-09 for missing translations to prevent cascading failures.
- System notifies Admin Dashboard via system log alert so Admin can manually retry translation later.
