Buduję
Technologia
Nie jestem programistką, a chciałam zbudować stronę, którą utrzymam sama. Dlatego każda decyzja poniżej stawia na prostotę i trwałość.
Claude Code
Zbudowałam tę stronę w Claude Code i VS Code. Na podstawie mojego „product requirements document”, Claude przygotował specyfikację techniczną i plan implementacji, a każdy etap kończył się punktem kontrolnym. Zanim coś uznałam za gotowe, musiało przejść automatyczne testy: jednostkowe, w przeglądarce oraz kontrole dostępności i układu.
Astro
Astro generuje całą stronę z góry. Odwiedzający dostają szybki, statyczny HTML, a serwera ani bazy danych nie trzeba pilnować, bo ich po prostu nie ma. Podstrony, które potrzebują odrobiny interaktywności (mapa, zakładki, wyszukiwarka), ładują niewielkie skrypty, a każda z nich pozostaje czytelna także bez nich.
TypeScript i JSON
TypeScript dla kodu, pliki JSON dla treści: doświadczenie zawodowe, wystąpienia i występy muzyczne to dane, a nie ręcznie pisane strony.
Pliki Markdown
Eseje to pliki Markdown. Aby opublikować wpis, po prostu wrzucam plik do folderu. Z tego jednego pliku powstają strona „Piszę”, wyszukiwarka, kanał RSS i „share card” (podgląd, który widzisz, gdy udostępniasz mój link). Bez tekstów alternatywnych do zdjęć wpis się nie opublikuje, więc o dostępności nie da się zapomnieć.
Mapa
Mapa jest rysowana podczas budowania strony, z otwartych danych geograficznych, jako zwykły SVG. Bez kafelków mapy, bez zewnętrznego serwisu mapowego, bez ładowania czegokolwiek z innych witryn.
Pagefind
Wyszukiwarka działa dzięki Pagefind. Indeks powstaje podczas budowania strony i działa w przeglądarce użytkownika, więc żadna zewnętrzna usługa nie widzi, czego szuka odwiedzający.
Czcionki
Czcionki są hostowane na własnym serwerze. Strona nie wysyła żadnych zapytań do zewnętrznych usług – ani po czcionki, ani po miniatury z YouTube’a, ani do analityki, a test automatycznie sprawdza, czy żadna podstrona nie łączy się z podmiotami trzecimi.
Motyw jasny, motyw ciemny
Motyw jasny i ciemny zależy od urządzenia. Przycisk ze słońcem i księżycem zmienia wygląd tylko na czas bieżącej wizyty.
Share cards
"Share cards" (obrazek wyświetlany po udostępnieniu linku) są rysowane podczas budowania strony, z przetłumaczonym imieniem i nazwiskiem oraz hasłem, po jednej na każdy esej.
Internacjonalizacja
Internacjonalizacja (i18n) oznacza takie zaprojektowanie strony, by dodanie nowego języka nie wymagało zmian w kodzie. Chociaż angielski jest pierwszym językiem tej strony, wielojęzyczność jest wpisana w jej architekturę od samego początku.
Routing i adresy URL
Angielskie strony nie mają prefiksu językowego (np. /writer/), ale strony w innych językach - tak (np. /pl/...). Język nie jest wykrywany automatycznie, to celowa decyzja: użytkownicy sami wybierają, w jakim języku chcą czytać. Każda strona zawiera też linki do swoich wersji w pozostałych językach, żeby wyszukiwarki mogły je ze sobą powiązać.
Strings, liczba mnoga, daty
Cały tekst znajduje się w plikach JSON, nic nie jest zapisane na sztywno w kodzie. Zdania zawsze pozostają w całości, bo sklejanie fragmentów psuje tłumaczenia, gdy tylko składnia języków się różni. Daty i liczby formatuje sama przeglądarka, według własnych zasad internacjonalizacji.
Od prawej do lewej
Układ opiera się na kierunkach logicznych (początek i koniec zamiast lewej i prawej strony), dzięki czemu w językach pisanych od prawej do lewej interfejs odbija się poprawnie. Wyjątkiem jest mapa: pokazuje rzeczywistą geografię, więc celowo się nie odbija.
Nazwy własne
Nazwy własne (firm, osób, kompozytorów, orkiestr, wydarzeń) są oznaczone, żeby żadne narzędzie tłumaczeniowe ich nie zmieniało. Nazwy opisowe są tłumaczone, a oryginał podany w nawiasie po tłumaczeniu.
Czcionki i systemy pisma
Czcionki obejmują litery łacińskie, w tym znaki diakrytyczne. Język w innym piśmie wymaga czcionki zapasowej, którą dodaje się razem z językiem.
Pseudolokalizacja
Wersje testowe zawierają dwa sztuczne języki. Pierwszy to angielski z akcentami, o około jedną trzecią dłuższy i ujęty w nawiasy, który pokazuje, gdzie tekst zostałby ucięty albo na siebie nachodzi. Drugi to wersja lustrzana, pisana od prawej do lewej. Żaden z nich nie trafia do użytkowników, służą wyłącznie do wyłapywania błędów i tekstu zapisanego na sztywno.
Lokalizacja
Lokalizacja (l10n) to praca polegająca na tłumaczeniu strony i kulturowym dostosowaniu do danego języka. Cel jest taki, aby tłumacz(ka), narzędzie tłumaczeniowe lub agent AI mogli pracować na podstawie jednego pliku. Nic nie jest wpisane do kodu na sztywno.
Lista kontrolna
Zanim tłumaczenie trafi na ekrany użytkowników, przechodzi automatyczną kontrolę: sprawdzana jest kompletność tekstów, znaczniki zastępcze (placeholdery), znaki diakrytyczne oraz ewentualne teksty zapisane na sztywno. Przy dodawaniu nowego języka dołączana jest też czcionka, jeśli wymaga jej dany system pisma.
Jeden język = jeden plik
Wszystkie teksty dla danego języka trafiają do jednego pliku. Cała treść, która ma trafić do użytkowników, znajduje się poza kodem.
Wytyczne redakcyjne i tłumaczeniowe
Tłumacz widzi kontekst w przypisach do każdego "stringu". Dodatkowo, osobne wytyczne zawierają wskazówki, co należy tłumaczyć, a czego nie ruszać (nazwy własne, nazwy produktów, numery katalogowe), jaki obowiązuje ton oraz konwencje nazewnicze. Wytyczne stworzone zostały do użytku zarówno ludzi, jak i agentów AI.
Czego nie tłumaczę
Eseje pozostają po angielsku. Nazwiska, kompozytorzy, numery katalogowe i nazwy firm pozostają w ich oryginalnych językach. Strona „Buduję”, którą właśnie czytasz, jest tłumaczona jak każda inna.