Przejdź do głównej zawartości

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​

  1. Zaloguj się do panelu administracyjnego.
  2. Otwórz stronę Profile (awatar w prawym górnym rogu albo oznaczenie EN / PL na górnym pasku).
  3. W sekcji Language wybierz English albo Polski, a następnie kliknij Save language.
  4. 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żkaPrzeznaczenie
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-languageUstawia 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/coverageRaportuje, 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/reloadWczytuje 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​

  1. Zadeklaruj katalog pakietów tłumaczeń w manifeście:

    // packages/modules/<my_module>/src/manifest.ts
    import { 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
    });
  2. 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 w src/, bo bundlesDir jest wyznaczane względem katalogu, w którym leży package.json modułu. Plik to płaski Record<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}\"."
    }
  3. 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>;
    }
  4. 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 wiersze translation_bundles na 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 wyliczenie SupportedLanguageSchema w @endora-commerce/contracts/src/platform-language.ts; admin-i18n.ts eksportuje je ponownie jako przestarzałe SupportedAdminLanguageSchema).
  • 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:

  1. Wpis w preferowanym języku użytkownika, w zakresie danego modułu.
  2. Wpis angielski w zakresie danego modułu.
  3. 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), JSONB entries, version z 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 przyczyna BundleLoadError (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.