Języki panelu administracyjnego
Każdy użytkownik panelu administracyjnego może wybrać własny język, a każdy moduł backendu może dostarczać własny pakiet przetłumaczonych tekstów. Od początku dostępne są polski i angielski; angielski jest wartością zastępczą w całej platformie.
Sam podsystem to pakiet workspace @endora-commerce/mod-i18n w packages/modules/_i18n/ (wewnętrzny
dla platformy — z podkreśleniem na początku, które nazwa w npm pomija). Jego pakiety tłumaczeń leżą
w katalogu głównym pakietu, packages/modules/_i18n/i18n/, bo platforma wyznacza bundlesDir
modułu względem jego własnego katalogu, a katalogiem pakietu jest ten, w którym leży jego
package.json. Kod działający w aplikacji panelu (TranslationProvider, useTranslation, mechanizm wyboru tekstu) jest w @endora-commerce/admin-kit/i18n, czyli w packages/admin-kit/src/i18n/.
Jak użytkownik zmienia język
- Zaloguj się do panelu administracyjnego.
- Otwórz stronę Profile (awatar w prawym górnym rogu albo oznaczenie
EN/PLna górnym pasku). - W sekcji Language wybierz English albo Polski, a następnie kliknij Save language.
- Cały panel od razu przełącza się na wybrany język. Wylogowanie nie jest potrzebne.
Wybór jest zapisywany w rekordzie użytkownika i towarzyszy mu na wszystkich urządzeniach: zalogowanie się w innej przeglądarce lub na innym komputerze daje ten sam język panelu, który został ostatnio zapisany.
Nowi użytkownicy (i ci, którzy nigdy nie wybrali języka) domyślnie widzą wersję angielską.
API publiczne
| Metoda i ścieżka | Przeznaczenie |
|---|---|
GET /api/v1/admin/i18n/bundles?language=<en|pl> | Zwraca połączony pakiet core i pakiety modułów dla żądanego języka oraz wektor version, który nigdy nie maleje i pozwala aplikacji panelu wykrywać odświeżenia. Uprawnienie: każdy zalogowany administrator. |
PATCH /api/v1/admin/me/preferred-language | Ustawia preferowany język wywołującego użytkownika. Treść: { "preferredLanguage": "en" | "pl" | null }. Idempotentne; null oznacza „brak zapisanego wyboru” → wersja angielska. Uprawnienie: każdy zalogowany administrator. |
GET /api/v1/admin/i18n/coverage | Raportuje, dla każdego modułu i języka, ile kluczy brakuje lub korzysta z wersji angielskiej. Opcjonalne parametry module, language i includeKeys zawężają wynik. Uprawnienie: settings:read. |
POST /api/v1/admin/i18n/reload | Wczytuje ponownie pakiety tłumaczeń wszystkich modułów z dysku do bazy danych, dla całej instancji, dzięki czemu zmienione tłumaczenia pojawiają się bez restartu. To przycisk Przeładuj tłumaczenia na ekranie pamięci podręcznej w Ustawieniach. Uprawnienie: settings:write. |
Odpowiedź inicjalizująca sesję (GET /api/v1/admin/me) zawiera preferredLanguage w obiekcie
adminUser, dzięki czemu aplikacja panelu może od razu ustawić <TranslationProvider> bez
dodatkowego zapytania.
Jak moduł dostarcza tłumaczenia
-
Zadeklaruj katalog pakietów tłumaczeń w manifeście:
// packages/modules/<my_module>/src/manifest.tsimport { defineModuleManifest } from '@endora-commerce/contracts';export const manifest = defineModuleManifest({id: 'my_module',name: 'My module',version: '1.0.0',dependencies: [],i18n: { bundlesDir: 'i18n' }, // ← add this}); -
Utwórz pliki JSON dla poszczególnych języków w
packages/modules/<my_module>/i18n/<lang>.json— w katalogu głównym pakietu, a nie wsrc/, bobundlesDirjest wyznaczane względem katalogu, w którym leżypackage.jsonmodułu. Plik to płaskiRecord<string, string>— klucze zapisuje się z kropkami ("actions.save"), a wartości to stringi. Znaczniki w rodzaju{name}są uzupełniane w czasie działania.// packages/modules/my_module/i18n/en.json{"actions.save": "Save","validation.required": "This field is required.","audit.userCreated": "Created user \"{email}\"."} -
Zastąp teksty wpisane bezpośrednio w kodzie panelu wywołaniami
useTranslation(scope):import { useTranslation } from '@endora-commerce/admin-kit/i18n';export function MyForm() {const t = useTranslation('my_module');return <button>{t('actions.save')}</button>;} -
Uruchom ponownie (albo zainstaluj ponownie) backend. Mechanizm uzgadniania pakietów przy starcie przechodzi przez każdy moduł, który deklaruje
manifest.i18n, i odświeża wierszetranslation_bundlesna podstawie plików JSON z dysku. Błędy trafiają do logu, ale nie przerywają startu.
Reguły i ograniczenia
- Obsługiwany zbiór to obecnie
['en', 'pl'](zamknięte wyliczenieSupportedLanguageSchemaw@endora-commerce/contracts/src/platform-language.ts;admin-i18n.tseksportuje je ponownie jako przestarzałeSupportedAdminLanguageSchema). - Pliki dla nieobsługiwanych języków są odrzucane przy instalacji.
- Moduł, który dostarcza jakikolwiek pakiet tłumaczeń, MUSI dostarczyć
en.json(angielski to wartość zastępcza w całej platformie). Pakiet polski jest mile widziany, ale opcjonalny — dodaj go w tym samym pull requeście co plik angielski. - Dwa moduły MOGĄ używać tego samego klucza (np.
actions.save); każdy pakiet należy do swojego modułu, więc teksty ze sobą nie kolidują. - Treści tworzone przez użytkowników (strony CMS, nazwy produktów, wpisy na blogu, wartości ustawień) są poza zakresem tej funkcji — są wyświetlane tak, jak je napisano, bez tłumaczenia.
Jak wybierany jest tekst
Każde wyszukanie przechodzi przez trzy kroki:
- Wpis w preferowanym języku użytkownika, w zakresie danego modułu.
- Wpis angielski w zakresie danego modułu.
- Dosłowny znacznik
${scope}.${key}(zawsze niepusty, aby interfejs nigdy nie był pusty).
Ten sam łańcuch stosują mechanizm w backendzie (I18nService.translate(...)) i mechanizm w
aplikacji panelu (packages/admin-kit/src/i18n/resolver.ts).
Wykrywanie brakujących tłumaczeń
Gdy trzeba sięgnąć po wartość zastępczą, backend zapisuje ustrukturyzowany wiersz w logu przez istniejący logger platformy:
{ "event": "i18n.fallback", "moduleId": "settings", "languageCode": "pl", "key": "actions.save", "fellBackTo": "en" }
Operatorzy mogą jednym poleceniem grep sprawdzić, czego brakuje w polskim pakiecie:
grep '"event":"i18n.fallback"' /var/log/b2b-backend.log | jq -r '"\(.languageCode) \(.moduleId).\(.key) → \(.fellBackTo)"' | sort -u
Aplikacja panelu zgłasza tę samą lukę jako console.warn w trybie deweloperskim
(import.meta.env.DEV), a na produkcji nic nie wypisuje.
Baza danych
Jedna migracja MikroORM (20260507T091405_i18n_admin_i18n_init.ts) wprowadza:
- Sekwencję
translation_bundles_version_seq(wektor unieważniania pamięci podręcznej). - Tabelę
translation_bundles— jeden wiersz dla każdej pary(module_id, language_code), JSONBentries,versionz wartością domyślnąnextval(translation_bundles_version_seq), więc każdy zapis (UPSERT) przesuwa sekwencję.
Kolumna admin_users.preferred_language (varchar(12), opcjonalna; NULL oznacza „brak zapisanego
wyboru” → traktowany jak angielski) należy do admin_users, który tworzy ją we własnej migracji
Migration20261114T002913AdminUsersPreferredLanguage (issue #611). Migracja tego modułu dodawała
ją wcześniej, a teraz nie odwołuje się już do admin_users; w bazie, która ma już tę kolumnę, nowa
migracja niczego nie zmienia.
translation_bundles.module_id nie ma klucza obcego — moduły wynikają z systemu plików, a za
sprzątanie odpowiada hook twardego odinstalowania, a nie ON DELETE CASCADE.
Dodanie trzeciego języka
Dodanie de (albo innego kodu BCP-47) to osobna funkcja, bo kosztem jest głównie praca
tłumaczy, a nie programistów. Zmiana schematu to jeden wiersz w
@endora-commerce/contracts/src/platform-language.ts:
export const SupportedLanguageSchema = z.enum(['en', 'pl', 'de']);
Potem każdy moduł, który wyświetla teksty w panelu, musi dostarczyć de.json (albo zaakceptować
wersję angielską jako zastępczą). Wybór języka na stronie Profile automatycznie uwzględni nowy kod.
Testy
Testy jednostkowe leżą obok implementacji:
backend/test/unit/_i18n/bundle-loader.unit.test.ts— każda przyczynaBundleLoadError(parse-failed, invalid-shape, unsupported-language-file, missing-fallback-bundle) oraz poprawna ścieżka i akceptacja pakietu tylko angielskiego.backend/test/unit/_i18n/missing-key-logger.unit.test.ts— postać ustrukturyzowanego wiersza logu.backend/test/unit/_i18n/i18n-service.unit.test.ts— trzystopniowy łańcuch wartości zastępczych i uzupełnianie znaczników.admin/test/i18n/resolver.test.ts— ten sam łańcuch po stronie aplikacji panelu.admin/test/i18n/interpolate.test.ts— wyrażenie regularne znaczników.