25 — Sistema de Internacionalização Global (i18n), Interface RTL (Árabe), Conversor de Unidades Automotivas & Hot-Swap de Voz gRPC (FASE 117)
Este documento detalha a arquitetura completa da FASE 117 — Globalização e Localização Automotiva em Tempo Real do Zenith AutoOS, projetada para permitir comercialização global com alternância instantânea (zero-restart) de textos da UI, layout Right-to-Left (RTL), escalas físicas do cluster/TPMS/ADAS 3D e modelos acústicos/cognitivos de voz (Whisper.cpp + Vosk + eSpeak + llama.cpp).
🏠 README · 📚 Documentação · ⬅️ 24 · Simulador · 26 · Settings ➡️
📑 Neste guia — 7 seções · ~7 min de leitura
- 🗺️ Visão geral em diagrama
- 1. Catálogo Estratégico de Locales (10 Variantes em 7 Mercados)
- 2. Motor Godot TranslationServer, Traduções .po/.csv e Tipografia Multilíngue
- 3. Lógica Dinâmica de Interface RTL (Árabe ar)
- 4. Motor Matemático de Unidades & Escala Analógica 2D/3D
- 5. Integração gRPC + Hot-Swap de Voz (Whisper.cpp / Vosk) & LLM Local
- 6. API FastAPI, WebUI & Validação Automatizada
Globalização: 10 locales, RTL árabe, conversão de unidades e hot-swap de voz.
🗺️ Visão geral em diagrama
flowchart LR
LOCALE["Locale pt-BR / en-US / ar"] --> I18N["zenith_i18n.py"]
I18N --> GODOT["Godot TranslationServer"]
I18N --> FE["React i18n"]
GODOT --> RTL["Layout RTL"]
I18N --> UNITS["Conversor de unidades"]
I18N --> VOICE["Hot-swap de voz gRPC"]
VOICE --> WHISPER["Whisper / Vosk / Piper"]
style I18N fill:#C084FC,color:#111,stroke:#E9D5FF
style RTL fill:#8B5CF6,color:#fff,stroke:#C4B5FD
style VOICE fill:#0A5C36,color:#fff,stroke:#C8A951Como ler: o diagrama resume o fluxo principal deste guia; os detalhes, pinagens, endpoints e trechos de código aparecem nas seções abaixo.
1. Catálogo Estratégico de Locales (10 Variantes em 7 Mercados)
Definido de forma canônica em locales.json, sincronizado com zenith_i18n.py, ZenithLocalization.gd e i18n.ts:
| Código | Mercado / Foco | Direção UI | Velocidade | Temperatura | Pressão TPMS | Escala Velocímetro | STT (whisper_lang) |
TTS (eSpeak) |
|---|---|---|---|---|---|---|---|---|
pt_BR |
Brasil (Padrão) | LTR | km/h |
°C |
Bar |
0–240 km/h |
pt |
pt-br |
pt_PT |
Portugal | LTR | km/h |
°C |
Bar |
0–240 km/h |
pt |
pt |
en_US |
EUA (Imperial) | LTR | mph |
°F |
PSI |
0–160 mph |
en |
en-us |
en_GB |
Reino Unido | LTR | mph |
°C |
Bar |
0–160 mph |
en |
en-gb |
es_419 |
América Latina | LTR | km/h |
°C |
Bar |
0–240 km/h |
es |
es-la |
es_ES |
Espanha | LTR | km/h |
°C |
Bar |
0–240 km/h |
es |
es |
de_DE |
Alemanha (Eurolook) | LTR | km/h |
°C |
Bar |
0–240 km/h |
de |
de |
ja_JP |
Japão (JDM Lexus/Toyota) | LTR | km/h |
°C |
Bar |
0–240 km/h |
ja |
ja |
zh_CN |
China (Smart EV) | LTR | km/h |
°C |
Bar |
0–240 km/h |
zh |
zh |
ar |
Oriente Médio (Hipercarros) | RTL | km/h |
°C |
Bar |
0–240 km/h |
ar |
ar |
Aliases comuns (en-us, en-uk, es-latam, ar-sa, pt-br, etc.) são normalizados por normalize_locale_code().
2. Motor Godot TranslationServer, Traduções .po/.csv e Tipografia Multilíngue
- Gerador Determinístico (generate_zenith_i18n.py): gera simultaneamente o catálogo tabular zenith_i18n.csv e os 10 catálogos GNU Gettext
.po(zenith.<locale>.po) com regrasPlural-Formsapropriadas para Latim, Japonês, Chinês e Árabe (nplurals=6). - Configuração Nativa (project.godot): registra
[internationalization]comlocale/fallback="pt_BR"e todas as 10 entradas emlocale/translations. - Carregamento Híbrido em Runtime (ZenithLocalization.gd): tenta
ResourceLoader.load()nos.pocompilados, faz parsing direto.poou fallback CSV caso necessário, invocaTranslationServer.set_locale(norm)e emitelocale_changed(locale_code, profile)para atualização imediata de todas as janelas Godot sem reiniciar o processo. - Font Fallback & Fontconfig:
- 60-zenith-fonts.conf define cadeias
<prefer>paraZenith Display,Zenith SanseZenith MonoincluindoNoto Sans Arabic,Noto Sans CJK JP,Noto Sans CJK SC,Noto SanseDejaVu Sans. - ZenithThemeEngine.gd anexa um
SystemFontcom essa mesma lista às fontes.ttfcarregadas via_load_custom_fonts().
- 60-zenith-fonts.conf define cadeias
3. Lógica Dinâmica de Interface RTL (Árabe ar)
Quando is_rtl == true:
- Inversão de Containers & Alinhamentos (
ZenithLocalization.apply_rtl_to_container()):- Alterna
Control.LAYOUT_DIRECTION_RTLvsLAYOUT_DIRECTION_LTR. - Espelha horizontalmente controles posicionados manualmente preservando a coordenada LTR original em metadados (
_ltr_x:container_width - ltr_x - w), respeitandortl_ignoreem overlays globais. - Inverte
Label.horizontal_alignment,Button.icon_alignmenteProgressBar.fill_mode(FILL_END_TO_BEGINem RTL).
- Alterna
- Espelhamento de Ícones Direcionais:
ZenithLocalization.is_directional_icon()+ZenithThemeEngine.load_svg_icon(..., flip_h=rtl)aplicamImage.flip_x()em ícones direcionais (lights_beam,navigation_compass) no CentralWindow.gd. - Espelhamento do Cluster 2D e do Velocímetro 3D:
- ClusterWindow.gd (
_apply_rtl_geometry()e_draw()) troca a posição do arco do velocímetro e do conta-giros/Track-Day (velocímetro vai para a direita emar) e inverte o alinhamento dos labels e barra TPMS. - Radar3D.gd (
_rebuild_3d_speedometer_scale()) moveAnalogSpeedometer3Ddex = -3.8(+14° Y) parax = +3.8(-14° Y).
- ClusterWindow.gd (
- Web UI React (
frontend/ecluster-ui/): alternadir={localeState?.rtl ? "rtl" : "ltr"}em App.tsx (document.documentElement.dir+lang), GhostCluster1920x720.tsx e cluster-ui/src/App.tsx.
4. Motor Matemático de Unidades & Escala Analógica 2D/3D
Centralizado em Python (zenith_i18n.py), GDScript (ZenithLocalization.gd) e TypeScript (i18n.ts):
- Velocidade:
km/h -> mph(* 0.621371192), alternando o mostrador numérico, distância V2X (km <-> mi), distância curta (m <-> ft) e a graduação radial completa:- Métrico (
km/h):0..240 km/h(passo20). - Imperial (
mph—en_US,en_GB):0..160 mph(passo20). - Tanto ClusterWindow.gd (2D
draw_line/draw_string) quantoAnalogSpeedometer3Dem Radar3D.gd (MeshInstance3Dticks +Label3D+NeedlePivot3D) reconstroem as marcações e recalculam o ângulo do ponteiro em tempo real.
- Métrico (
- Temperatura:
°C -> °F(c * 9/5 + 32), aplicada ao arrefecimento, sensores TPMS e alertas térmicos do assistente cognitivo zenith_llm_ncm.py (_synthesize_offline_diagnosis). - Pressão TPMS:
Bar <-> PSI(bar * 14.5037738), exibida nos 4 pneus em ClusterWindow.gd e nos dashboards web.
5. Integração gRPC + Hot-Swap de Voz (Whisper.cpp / Vosk) & LLM Local
CentralWindow.gd (LocaleSelector)
└─▶ ZenithMaster.request_locale_change()
├─▶ Protobuf frame 'ZL' (ws://127.0.0.1:8766) ─▶ ZenithGrpcProtobufHub
└─▶ JSON set_locale (ws://127.0.0.1:8765) ──────▶ adas_radar.py ─▶ send_grpc_set_locale()
│
┌──────────────────────────────────────────────────────────────────────┘
▼
ZenithTelemetryService/SetLocale (:50051 Protobuf LocaleConfigRequest / Fallback /run/zenith/grpc_cmd.sock)
├─▶ /data/profiles/locale.json (Persistência)
├─▶ /run/zenith/voice_cmd.sock ──▶ zenith_voice_agent.py (VoiceAgent.set_locale)
│ ├─ Atualiza modelo Whisper.cpp (ggml-*.bin) & idioma (-l <whisper_lang>)
│ ├─ Atualiza diretório Vosk (vosk-model-*) & voz TTS eSpeak
│ └─ Recarrega wake_words_by_locale / phrases_by_locale / tts_by_locale
└─▶ /run/zenith/llm_cmd.sock ────▶ zenith_llm_ncm.py (VehicleCognitionEngine.set_locale)
├─ Troca prompt LOCALE_PROMPTS + modelo GGUF
└─ Ativa tokenização multilíngue (Latim + Árabe + CJK bigramas) & unidades de diagnóstico- Proto3 & Wire Binário: zenith_telemetry.proto define
LocaleConfigRequest,LocaleConfigAckerpc SetLocale/rpc GetLocale; zenith_proto_codec.py e ProtobufWire.gd compartilham o enquadramentoLOCALE_FRAME_MAGIC(0x5A 0x4C="ZL") + CRC32 IEEE. - Pacote Buildroot
whisper-cpp: Config.in + whisper-cpp.mk (v1.7.4, CMake comAVX2/FMA/F16C) habilitado em zenith_autoos_defconfig viaBR2_PACKAGE_WHISPER_CPP=y, com modelos em/data/voice/whisper/declarados em zenith-runtime.conf e diretórios/etc/zenith/i18n,/opt/zenith/i18n,/opt/zenith/hmi/project/translationsgarantidos em post-build.sh. - Normalização Unicode de Voz & RAG:
normalize_text()em zenith_voice_agent.py enormalize_pt()/tokenize_multilingual()em zenith_llm_ncm.py aplicamNFKC, removem diacríticos latinos combinantes (0x0300..0x036F) e tashkeel árabe (0x064B..0x065F, normalizando أ/إ/آ/ة/ى) preservando intactos os sinais diacríticos dakuten/handakuten do japonês (kana), hanzi e bigramas CJK, junto a palavras-chave multilíngues em vehicle_manuals.json e voice_intents.json.
6. API FastAPI, WebUI & Validação Automatizada
- Backend REST & WebSocket: locale.py (
GET /api/locale/supported,GET /api/locale/state,POST /api/locale/set,POST /api/locale/convert) via locale_service.py, modeloLocaleStateem vehicle.py e difusão"locale"em/ws/telemetry(main.py). - Suites de Teste:
- Embarcado & IPC/Voz/LLM:
test_fase_117_i18n_rtl_units_grpc_voice_and_llmem tests/test_zenith_embedded.py. - Backend FastAPI:
test_fase_117_i18n_locale_endpoints_and_unitsem backend/tests/test_api.py. - Pipelines CI: .github/workflows/zenith-ci.yml e .gitlab-ci.yml.
- Embarcado & IPC/Voz/LLM:
⬅️ 24 · Simulador · ⬆️ Topo · 📚 Índice · 26 · Settings ➡️
Zenith AutoOS 11.0 · Documentação técnica · Novembro de 2026 · README principal