Tłumaczenie witryny dokumentacji
Witryna Docusaurus w katalogu docs/ udostępnia treści dla użytkowników po angielsku i po
polsku. Językiem roboczym repozytorium — kodu, specyfikacji i komunikatów commitów — pozostaje
angielski. Polską dokumentację pisze się ręcznie, w tym samym pull requeście co zmianę
angielską: ani CI, ani build produkcyjny nie zawierają kroku tłumaczenia maszynowego.
Ta strona opisuje proces tłumaczenia witryny dokumentacji. Pakiety tekstów panelu
administracyjnego (katalog i18n/ każdego modułu, w katalogu głównym jego pakietu) to osobny
system — zobacz Tłumaczenia panelu administracyjnego.
Co trzeba przetłumaczyć
pnpm --filter backend run check:docs-translations wylicza wszystkie angielskie źródła i dla
każdego języka z docs/locales.config.json → translateLocales (w v1 tylko pl) oczekuje
przypięcia tłumaczenia oraz gotowego pliku markdown:
| Warstwa | Źródło angielskie | Klucz sourcePath przypięcia |
|---|---|---|
| Strony witryny pisane ręcznie | docs/docs/**/*.md (bez kategorii generowanych) | ścieżka względem katalogu głównego repozytorium, np. docs/docs/intro.md |
| Referencja modułów (generowana) | docs/docs/module-reference/*.md | generated:module-reference/<slug> |
| Mapa modułów (generowana) | docs/docs/modules/module-map.generated.md | ścieżka względem katalogu głównego repozytorium |
| Strony należące do modułów | docs/**/*.md w katalogu głównym pakietu każdego modułu | ścieżka względem katalogu głównego repozytorium |
Ścieżki wymienione w docs/translation-skip.json są pomijane (dziś jest to
docs/docs/contributing/translations.md, czyli słownik tłumaczeń panelu administracyjnego).
Elementy stałe witryny — pasek nawigacji, stopkę i etykiety kategorii paska bocznego
zadeklarowane w docs/sidebars.js i docs/sidebars.modules.generated.js — tłumaczy się w
plikach, z których Docusaurus je odczytuje, a tym plikiem nie jest code.json. Zasadę opisuje
następna sekcja. Pomyłka w tym miejscu niczego nie tłumaczy i niczego nie zgłasza — właśnie dlatego
cała polska nawigacja trafiła kiedyś na produkcję po angielsku.
Gdzie należy identyfikator komunikatu
Każdy identyfikator komunikatu ma dokładnie jeden plik, z którego Docusaurus go odczyta. Wpisany gdziekolwiek indziej nic nie robi: build się udaje, strona się wyświetla, a tekst zostaje w języku źródłowym.
Identyfikatory wyprowadzane z konfiguracji należą do plików tłumaczeń motywu i wtyczki. To
identyfikatory, które Docusaurus wyprowadza z themeConfig w docs/docusaurus.config.js oraz z
docs/sidebars.js:
| Identyfikatory | Plik w docs/i18n/<locale>/ |
|---|---|
title, logo.alt, item.label.<Label> — pasek nawigacji | docusaurus-theme-classic/navbar.json |
copyright, logo.alt, link.title.<Title>, link.item.label.<Label> — stopka | docusaurus-theme-classic/footer.json |
sidebar.<name>.category.<key> wraz z .link.generated-index.title / .description, sidebar.<name>.link.<key> | docusaurus-plugin-content-docs/current.json |
<key> kategorii to category.key ?? category.label. Identyfikatory paska nawigacji i stopki
zapisuje się w ich własnych plikach bez prefiksu — title, nigdy theme.navbar.title.
Identyfikatory emitowane przez komponenty należą do code.json. To teksty, które wyświetlają
komponenty motywu i wtyczek — własne teksty motywu Docusaurus, takie jak
theme.navbar.mobileLanguageDropdown.label, oraz teksty wtyczki wyszukiwania.
docs/i18n/<locale>/code.json jest dla nich właściwym miejscem i nie zawiera niczego innego.
sidebar.<name>.doc.* nie działa nigdzie. Wpis w postaci samej ścieżki, 'some/doc', w
którymkolwiek pliku paska bocznego wtyczka content-docs normalizuje z translatable: false, więc
żaden taki identyfikator nie jest odczytywany z żadnego pliku. Polska etykieta dokumentu w pasku
bocznym pochodzi z tytułu samej polskiej strony — z sidebar_label albo title w jej front
matterze. Wpisy typu doc nie wymagają żadnego wpisu w pliku tłumaczeń.
pnpm --filter backend run check:docs-translations wyprowadza oczekiwany zbiór
identyfikatorów z obu plików konfiguracyjnych, a nie z listy
(backend/scripts/lib/docs-chrome-messages.ts). Nowa pozycja paska nawigacji albo nowa kategoria
zostaje więc zgłoszona przy pierwszym pojawieniu się — jako chrome-message-missing, gdy brakuje
jej we właściwym pliku, i jako chrome-message-inert, gdy trafiła do code.json.
Edycja w trzech krokach
Postępuj tak, gdy zmieniasz jedną stronę angielską i jej polskie tłumaczenie. Kroki 1–2 to edycja plików, krok 3 to lokalna kontrola.
-
Zmień angielskie źródło — stronę pisaną ręcznie w
docs/docs/albo stronę w katalogudocs/modułu, w katalogu głównym jego pakietu (nie wsrc/). -
Napisz lub zaktualizuj polską stronę w tym samym pull requeście, w pliku
docs/i18n/pl/docusaurus-plugin-content-docs/current/<docId>.md(np.docs/docs/intro.md→.../current/intro.md, własnydocs/catalog.mdmodułucatalog→.../current/modules/catalog.md). Ta strona jest tłumaczeniem — to z niej Docusaurus buduje witrynę.- Jeśli zmieniasz etykietę kategorii paska bocznego albo tekst paska nawigacji lub stopki, dodaj odpowiedni identyfikator do pliku wskazanego w sekcji Gdzie należy identyfikator komunikatu powyżej. Wpis dokumentu w pasku bocznym nie wymaga identyfikatora.
-
Przypnij stronę na nowo, a potem uruchom kontrolę kompletności:
pnpm --filter backend run docs:translations:pin docs/docs/intro.mdpnpm --filter backend run check:docs-translationsPolecenie przypinające zapisuje skrót tej treści strony angielskiej, z którą polska strona jest teraz zgodna (sekcja Przypięcia tłumaczeń poniżej). Podaj strony, które przetłumaczyłeś — ścieżką strony angielskiej albo kluczem przypięcia. Bez argumentów polecenie przypina na nowo każdą stronę, której angielska treść się zmieniła. Przypięcie mówi kontroli, że tłumaczenie jest aktualne, więc przypinaj tylko strony, które naprawdę zaktualizowałeś.
Kod wyjścia
0oznacza, że każde źródło ma aktualne przypięcie, gotowy plik, z którego Docusaurus potrafi odczytać tytuł, a każdy identyfikator elementów stałych jest w pliku, który go odczytuje. Kod wyjścia2wypisuje zgłoszeniamissing-translation,stale-translation,malformed-pin,missing-sidebar-message,chrome-message-missing,chrome-message-inertalbodoc-title-unresolvable.
Przypięcia tłumaczeń
Przypięcie to mały plik JSON w docs/translation-cache/<locale>/<sourceKey>.json. Ukośniki w
ścieżce źródłowej zamieniają się w --, np. docs/docs/intro.md → docs--docs--intro.md.json.
Plik mówi, z której treści strony angielskiej powstało tłumaczenie, i nic poza tym:
{
"sourcePath": "docs/docs/intro.md",
"sourceHash": "<sha256 of English body>",
"locale": "pl",
"meta": {
"provider": "manual",
"updatedAt": "2026-09-17T12:00:00.000Z"
}
}
sourceHash to sha256 znormalizowanej treści strony angielskiej, bez front mattera YAML
(hashSourceBody() w backend/scripts/lib/docs-translation-cache.ts). Sama zmiana front mattera
strony angielskiej nie sprawia więc, że tłumaczenie staje się nieaktualne. Przypięcia zapisuj
poleceniem docs:translations:pin, a nie ręcznie. Polecenie odmawia i niczego nie zapisuje, gdy
strona do przypięcia nie ma polskiej wersji, gdy treść polskiej strony jest treścią angielską albo
gdy podana nazwa nie jest źródłem dokumentacji. Aktualnego przypięcia nie zmienia.
Przypięcie zawierające cokolwiek innego kontrola zgłasza jako malformed-pin. Dotyczy to
nierozwiązanego znacznika konfliktu oraz kopii całej strony w polu content, którą wpisy
zawierały przed zgłoszeniem #671.
Rozwiązywanie konfliktu w przypięciu. Dwie gałęzie, które zmieniają tę samą stronę angielską,
są w konflikcie na jej sourceHash. Weź którąkolwiek stronę konfliktu, upewnij się, że polska
strona odpowiada scalonej stronie angielskiej, i uruchom
pnpm --filter backend run docs:translations:pin <page>. Skrót jest wyliczany, więc generuje się
go na nowo, a nie scala.
W polskim tekście zostaw bez zmian bloki kodu, kod w treści, adresy URL, ścieżki plików, polecenia CLI, literały JSON/YAML, metody i ścieżki HTTP oraz identyfikatory modułów.
Polska terminologia
Polskie strony pisz terminami z sekcji Terminologia witryny dokumentacji — jeden słownik obowiązuje panel administracyjny i tę witrynę, dzięki czemu moduł nakładkowy jest modułem nakładkowym na każdej stronie, a nie tylko na niektórych. Tłumacz sens, a nie zdanie: polski szyk, żadnych angielskich czasowników z polską końcówką i zapożyczenie tylko tam, gdzie słownik je zostawia. Jeśli potrzebnego terminu brakuje, dodaj jego wiersz w tym samym pull requeście.
Wygenerowane strony angielskie
pnpm --filter backend run composer:generate generuje wyłącznie po angielsku:
- strony referencji modułów w
docs/docs/module-reference/, - mapę modułów w
docs/docs/modules/module-map.generated.md, - wygenerowany fragment paska bocznego
docs/sidebars.modules.generated.js.
Po ponownym wygenerowaniu ręcznie odwzoruj wersję polską w docs/i18n/pl/:
- gotowe pliki w
docs/i18n/pl/docusaurus-plugin-content-docs/current/module-reference/oraz.../modules/, - identyfikator
sidebar.main.category.<key>wdocs/i18n/pl/docusaurus-plugin-content-docs/current.jsondla każdej nowej kategorii zadeklarowanej w ponownie wygenerowanymdocs/sidebars.modules.generated.js. Nowe wpisy typudocniczego nie wymagają — ich polska etykieta to tytuł gotowej strony.
Następnie uruchom docs:translations:pin dla ponownie wygenerowanych stron. Ich przypięcia mają
klucze generated:module-reference/<slug>, a mapy modułów — ścieżkę względem katalogu głównego
repozytorium.
Nie zmieniaj wygenerowanych plików angielskich z myślą o wersji polskiej. Aktualizuj drzewo i18n, a potem przypnij strony na nowo.
pnpm --filter backend run docs:collect (kopiuje strony angielskie do docs/docs/modules/) nie
zapisuje niczego po polsku; polską wersję językową w czasie budowania dostarczają pliki i18n
zatwierdzone w repozytorium.
Weryfikacja dodatkowa
Gdy check:docs-translations przejdzie, sprawdź, czy budują się obie wersje językowe:
pnpm --filter docs run build
onBrokenLinks: 'throw' musi przejść zarówno dla wersji angielskiej, jak i polskiej.
Dodawanie kolejnego języka
Kolejne języki się dokłada — bez przebudowy procesu. Aby dodać na przykład niemiecki:
- Dopisz
"de"dolocalesitranslateLocaleswdocs/locales.config.json. - Dodaj
label(i powiązane teksty motywu) dladewdocs/docusaurus.config.js→i18n.localeConfigs. - Przygotuj pliki tłumaczeń elementów stałych, kopiując pliki z
pli tłumacząc je —docs/i18n/de/docusaurus-theme-classic/navbar.jsonifooter.json,docs/i18n/de/docusaurus-plugin-content-docs/current.json, a takżedocs/i18n/de/code.json, wyłącznie dla identyfikatorów emitowanych przez komponenty (sekcja Gdzie należy identyfikator komunikatu powyżej). - Ręcznie napisz gotowy markdown w
docs/i18n/de/docusaurus-plugin-content-docs/current/dla każdego angielskiego źródła (te same warstwy co dla polskiego), a potem uruchompnpm --filter backend run docs:translations:pin, które zapisze przypięcia wdocs/translation-cache/de/. - Uruchom
pnpm --filter backend run check:docs-translationsorazpnpm --filter docs run build— oba muszą zakończyć się kodem0.
Wszystkie miejsca, które z tego korzystają (check-docs-translations.ts,
pin-docs-translations.ts, konfiguracja Docusaurus,
przyszłe hooki), odczytują loadDocsLocales() z docs/locales.config.json — nie wpisuj kodów
języków na stałe w skryptach.
Zobacz także
- Tłumaczenia panelu administracyjnego — polski słownik i proces pracy z
pakietami
i18n/każdego modułu.