Skip to main content

Admin UI Translations

This page covers Admin UI string bundles (each module's own i18n/ directory) and holds the one Polish glossary both translation systems use. The documentation site (docs/) has a separate manual bilingual workflow — cache entries, materialised markdown under docs/i18n/pl/, and check:docs-translations; see Documentation site i18n. Its platform and architecture vocabulary is under Documentation-site terminology below.

The Admin UI is bilingual at launch — every user-visible string is shipped in both English (the platform-wide source of truth) and Polish. The mechanism is a set of filesystem bundles per module, the lifecycle reconciler that loads them, the in-process resolver and the language picker. This page is the source of truth for the in-house Polish glossary and the workflow for adding new strings without regressing coverage.

Polish glossary​

Use the canonical Polish rendering of every recurring B2B-commerce term on every screen. Consistency beats local cleverness — when in doubt, look here first and only propose a glossary edit if the term genuinely does not fit.

English termPolish termNotes
sales channelkanał sprzedażyalways lowercase mid-sentence
sales channelskanały sprzedażyplural
price listcennik
price listscennikiplural
price bookcennikthe D-287 model's price list; same Polish word
base pricecena bazowaa product's price in the base book of a currency
catalogue pricecena katalogowaalso "list price" beside the buyer's price
buyer pricecena kupującego
sale pricecena promocyjnaa sale book's price
price precedencekolejność centhe order of the twelve buyer cells
price explainerwyjaśnienie cenythe admin screen
quantity tierpróg ilościowy
audience (price book)odbiorcywho a price book's prices are for
quote requestzapytanie ofertowethe "RFQ" concept
quote requestszapytania ofertoweplural
orderzamówienie
orderszamówieniaplural
customerklientindividual; B2B-buyer side
organisationorganizacjacorporate buyer
accountkontologin/admin context
admin userużytkownik admina
rolerola
permissionuprawnienie
audit logdziennik audytu
two-step verificationweryfikacja dwuetapowathe one MFA term; never "2FA" or "two-factor"
productprodukt
productsproduktynom. plural for 2-4; produktów for 5+
variantwariant
attributeatrybut
attributesatrybuty
attribute setzestaw atrybutów
categorykategoria
gallerygaleria
attachmentzałącznik
inventorystany magazynowethe noun for "warehouse stock"
inventory levelpoziom stanu
stockstan magazynowy
warehousemagazyn
warehousesmagazynyplural
promotionpromocja
promotionspromocjeplural
tax ratestawka podatku
megamenumegamenuproper noun; remains untranslated
blog postwpis na blogu
CMS pagestrona CMS
dictionary entrywpis słownika
dictionarysłownik
settingustawienie
settingsustawieniaalso the screen name
setting groupgrupa ustawień
global valuewartość globalnasettings inheritance
channel overridenadpisanie kanałusettings inheritance
value (setting)wartość
comparisonporównaniethe customer-facing compare feature
shopping listlista zakupów
saved viewzapisany widoka named list setup; plural "zapisane widoki"
shared (saved view)udostępnionynot "współdzielony"
credit limitlimit kredytowy
minimum order quantityminimalna ilość zamówienia"Minimum" alone once the context is clear
packaging unitjednostka opakowania
returnablepodlega zwrotowinegated: "niepodlegający zwrotowi"
bulk editedycja masowabutton: "Edycja masowa"
assetzasóbgeneric file/image asset
integrationintegracja
webhookwebhookproper noun; remains untranslated
API keyklucz API
importimport
exporteksport
SEOSEOproper noun; remains untranslated
profileprofil"My profile" → "Mój profil"
loginlogowaniethe noun; the action is "zaloguj się"
sign in (verb)zaloguj się
sign out (verb)wyloguj się
savezapiszbutton label; lowercase in sentences
save changeszapisz zmianybutton label
discardodrzućbutton label
cancelanulujbutton label
deleteusuńbutton label
resetresetujbutton label
reset to defaultprzywróć domyślnebutton label
editedytujbutton label
createutwórzbutton label
adddodajbutton label
removeusuńreuse "usuń" — context disambiguates
searchszukajverb (button); the noun is "wyszukiwarka"
loadingwczytywanieprogress label
savingzapisywanieprogress label
empty / no resultsbrak wyników
settings page titleUstawieniacapitalised page title
products page titleProdukty
categories page titleKategorie
customers page titleKlienci
organisations pageOrganizacje

Documentation-site terminology​

The Polish pages of the documentation site (docs/i18n/pl/) use the domain terms above and the platform vocabulary below. The aim is Polish a Polish engineer would write, not English with Polish endings: a technical loanword stays only where Polish developers actually say it (storefront, build, worker, endpoint), and an English verb is never conjugated as Polish ("failuje", "shipuje", "shadowuje" are always wrong). Identifiers, commands, file paths, setting keys and environment variables (DEPLOYMENT, overlay:check, apps/<deployment>/) stay exactly as they are in code. An Admin UI label quoted in bold (a button, a tab, a screen name) stays as it reads in the English page unless the translator has checked the Polish label in the module's i18n/pl.json; a guessed Polish label sends the reader looking for a button that does not exist.

English termPolish termNotes
modulemoduł
core (module)rdzeń; moduł rdzenia"core" may follow once in brackets: rdzeń (core)
overlay modulemoduł nakładkowynever "moduł overlay"; add "(overlay)" on a page's first mention
overlay (layer)nakładka; warstwa nakładkowaoverlay pattern → wzorzec nakładki
deploymentwdrożeniereference deployment → wdrożenie referencyjne
instanceinstancjathe tree npx create-endora-commerce writes
storefrontstorefrontthe application; "sklep" when addressing a merchant
Admin UI, admin panelpanel administracyjny"panel" alone once the context is clear
operatoroperator
activation; enable; disableaktywacja; włączyć; wyłączyć
availability (platform)dostępnośćthe deployment-owned axis, beside activation
install; uninstallinstalacja; odinstalowanie
install hookhook instalacyjny"hook" is the established loanword
lifecyclecykl życia
migrationmigracja
schemaschemat
entityencja
service (DI)usługanot "serwis"
container (DI)kontener
registration; registerrejestracja; rejestrować
decorate; decorationdekorować; dekoracja
wrap; wrapperopakować; wrapper
route; route handlertrasa; handler trasy
endpointendpoint
worker; queue consumerworker; konsument kolejkijob → zadanie
event bus; eventszyna zdarzeń; zdarzenieEventBus stays as the identifier
Command BusCommand Busproper name
port; adapterport; adapter
composition; composekompozycja; składaćcomposition root stays "composition root"
manifestmanifest
registryrejestr
dependencyzależność
package; extension packagepakiet; pakiet rozszerzenia
releasewydaniepatch/major release → wydanie poprawkowe / główne
changesetchangesetthe file .changeset/*.md
build; build timebuild; czas budowaniathe verb is "zbudować", not "zbuildować"
runtimeczas działania
ship (a package ships X)zawierać; dostarczaćnever "wysyłać", which means sending a message
fail (a build, a check)kończyć się błędem; nie przechodzićnever "failować"
fail closedodmawiać w razie wątpliwości"(fail-closed)" may follow once in brackets
refuse; refusalodrzucać; odmowa
seampunkt rozszerzenianever "szew"
contribution; contribution pointwkład; punkt wpięciawhat a module adds to a host surface (a nav entry, a zone)
capabilitymożliwość
overridenadpisanie; nadpisać
shadow (a file)przesłaniać
check (check:* script)kontrolathe script name stays as written
guardzabezpieczenie
tenant; tenant isolationtenant; izolacja tenantówthe Organization is the tenant; inflect: tenanta, tenantów
channel scopingzawężanie do kanału sprzedaży
setting keyklucz ustawienia
permission codekod uprawnienia
command palettepaleta poleceń
divergence reportraport rozbieżności
customisation ladder; rungdrabina dostosowań; stopień
payload; request bodytreść; treść żądania
specification; specspecyfikacja
pull request; mergepull request; scalenie
commit (verb)zatwierdzić (commit)the noun "commit" stays
fallbackwartość zastępczaor "ścieżka zapasowa" for a code path
seed datadane początkowe
connector (PIM, ERP)konektor"konektor PIM", "konektor ERP"
invoice ledgerksięga fakturmatches the module's Polish UI label
provider (feed, taxonomy, external service)dostawca"provider" stays only inside identifiers
product feed; feedfeed produktowy; feedinflect: feedu, feedy; matches the module's Polish UI label
run (a feed generation)generowanie"przebieg" for a job run or a test run
reconciler; reconcilemechanizm uzgadniający; uzgadniać

Adding a new term​

When a new module or screen introduces a B2B-domain concept that needs a canonical Polish rendering, add a row to the glossary table above in the same PR that introduces the strings. Include:

  • the English term as it appears in the UI source-of-truth strings,
  • the agreed Polish rendering,
  • a one-line note when the term is conditional (gender, capitalisation, mid-sentence form, abbreviation rules).

If the team disagrees on a Polish rendering, the PR author files a glossary amendment as a separate PR and references the open module PR — the module PR unblocks once the glossary lands.

Adding a new user-visible string​

Workflow for any developer adding a new string to the Admin UI:

  1. Find the owning module: usually packages/modules/<module>/i18n/. Chrome strings (AppShell, top bar, command palette, profile, login, language picker) live in packages/modules/_i18n/i18n/ under the core scope — the _i18n module ships as the package @endora-commerce/mod-i18n, and a module package keeps its bundles at its own root rather than under src/.
  2. Pick a stable key path: dotted lowercase, e.g. page.title, actions.save, editor.applyTo.label. Reuse existing keys where the meaning is identical; do not invent parallel keys for "Save".
  3. Add the English entry to en.json. This is the canonical meaning; if it includes a count or a name, use {name} placeholders.
  4. Add the Polish entry to pl.json. Consult the glossary above. Match the placeholder list exactly. For counts in running text use the three-pattern strategy described under Polish quality bar.
  5. Replace the hard-coded literal in the source:
    <Button>{t('actions.save')}</Button> // where t = useTranslation('moduleId')
    For server-emitted strings:
    await i18nService.translate('moduleId', 'key', recipientLanguage, params);
  6. Restart the backend so the lifecycle reconciler upserts the bundle into translation_bundles. (Bundle files are read by readFileSync, not by tsx watch — JSON edits don't trigger a hot reload.)
  7. Local check:
    pnpm --filter backend run i18n:coverage --modules <moduleId> --strict
    Exit code 0 = clean. Any non-zero exit lists the keys to fix.
  8. CI gate: every PR that adds a user-visible string MUST add both English and Polish entries in the owning bundle. CI runs pnpm --filter backend run i18n:coverage -- --strict for bundle parity and pnpm --filter backend run i18n:hardcoded -- ../admin/src --strict for JSX literals. The coverage diagnostic enforces bundle-side completeness; the hardcoded-string lint enforces the Admin UI source side. A PR that drops a Polish entry or ships a hard-coded user-visible JSX string fails before merge.

Notification bell entries​

An entry on the Admin UI's notification bell is one stored row read by several administrators, each in a language of their own, and long after it was written. The module that records it therefore cannot translate it. It records two things: the finished English sentence, and the address of that sentence in its own bundle.

await adminNotifications.record({
audience: 'admin_user',
targetAdminUserId,
kind: 'crm.opportunity.assigned',
// Always: the sentence shown when the message below cannot be resolved.
title: `Opportunity ${number} was assigned to you`,
// Optional: resolved by the bell in the reader's language.
titleMessage: {
scope: 'crm', // the bundle: a module id, or `core`
key: 'notifications.assigned.title', // a key in that bundle, en + pl
params: { number }, // strings and numbers only
},
});

bodyMessage does the same for body. Both fields are optional, and a caller that passes neither is recorded and shown exactly as before.

Rules the port and the bell hold you to:

  • title is never optional and is always English. The bell shows it when the entry carries no message, when no loaded bundle holds the key — the recording module may be switched off or uninstalled by the time the entry is read — and when the template names a placeholder the entry has no param for. A raw key is never shown.
  • bodyMessage needs a body to fall back to; the port refuses it otherwise.
  • Params are strings and finite numbers. They are drawn as text, never as markup, and the port refuses anything else.
  • A param may say no more than the sentence does. A bell is read outside the tenant scope, so whatever is kept out of title is kept out of params. The simplest way to hold that is a test asserting that the English template filled with the params is the title — crm's crm-notifier.test.ts is the model.
  • Add the key to both en.json and pl.json, with the same placeholders.
  • A sentence that loses a clause is a second key, not the same key with an empty param: {author} mentioned you… and You were mentioned… are two entries in the bundle.

Polish quality bar​

  • Native, not literal: Polish strings are written for a native Polish reader, not transliterated from English. A reviewer pass before merge is required.
  • Locale formatting: numbers, dates, currencies, and relative times must use Polish locale conventions. Use browser-native Intl.NumberFormat('pl-PL', …) / Intl.DateTimeFormat('pl-PL', …) at the rendering layer; never encode locale assumptions in the bundle entry itself.
  • Plurals: the translation mechanism deliberately ships singular-vs-plural only — ICU MessageFormat is deferred. For Polish counts in running text follow the three-pattern strategy: avoid the count in text, use a colon phrasing, or branch on the count in code.
  • Length: Polish strings tend to be longer than English. UI containers must grow, wrap, or expose a tooltip — never clip or overflow.