Intlayer

--- createdAt: 2025-11-24 updatedAt: 2025-11-24 title: Kompilator kontra deklaratywne i18n description: Eksploracja kompromisów architektonicznych między "magiczna" internacjonalizacją opartą na kompilatorze a eksplicytnym, deklaratywnym zarządzaniem treścią. keywords: - Intlayer - Internacjonalizacja - Blog - Next.js - JavaScript - React - i18n - Kompilator - Deklaratywne slugs: - blog - compiler-vs-declarative-i18n --- # Argumenty za i przeciw internacjonalizacji opartej na kompilatorze Jeśli budujesz aplikacje webowe od ponad dekady, wiesz, że internacjonalizacja (i18n) zawsze była punktem zapalnym. Często jest to zadanie, którego nikt nie chce wykonywać — wyciąganie stringów, zarządzanie plikami JSON i martwienie się o zasady pluralizacji. Niedawno pojawiła się nowa fala **narzędzi i18n opartych na kompilatorze**, obiecujących, że ta uciążliwość zniknie. Oferta jest kusząca: **Po prostu pisz tekst w swoich komponentach, a narzędzie budujące zajmie się resztą.** Bez kluczy, bez importów, po prostu magia. Ale jak to bywa ze wszystkimi abstrakcjami w inżynierii oprogramowania, magia ma swoją cenę. W tym wpisie na blogu przeanalizujemy przejście od bibliotek deklaratywnych do podejść opartych na kompilatorze, ukryte długi architektoniczne, które wprowadzają, oraz dlaczego „nudny" sposób może nadal być najlepszym rozwiązaniem dla profesjonalnych aplikacji. ## Spis treści <TOC/> ## Krótka historia internacjonalizacji Aby zrozumieć, gdzie jesteśmy, musimy spojrzeć wstecz, skąd zaczęliśmy. Około 2011–2012 krajobraz JavaScript wyglądał zupełnie inaczej. Bundlery, jakie znamy dzisiaj (Webpack, Vite), nie istniały lub były na bardzo wczesnym etapie rozwoju. Sklejaliśmy skrypty bezpośrednio w przeglądarce. W tym okresie powstały biblioteki takie jak **i18next**. Rozwiązały one problem w jedyny możliwy wtedy sposób: **Słowniki w czasie wykonywania**. Ładowało się ogromny obiekt JSON do pamięci, a funkcja wyszukiwała klucze na bieżąco. Było to niezawodne, jawne i działało wszędzie. Przenieśmy się do dziś. Mamy potężne kompilatory (SWC, bundlery oparte na Rust), które potrafią analizować Abstrakcyjne Drzewa Składniowe (AST) w ciągu milisekund. Ta moc dała początek nowemu pomysłowi: _Dlaczego ręcznie zarządzamy kluczami? Dlaczego kompilator nie może po prostu zobaczyć tekstu "Hello World" i zamienić go za nas?_ Tak narodziło się i18n oparte na kompilatorze. > **Przykład i18n opartego na kompilatorze:** > > - Paraglide (Moduły poddane tree-shakingowi, które kompilują każdą wiadomość do małej funkcji ESM, dzięki czemu bundlery mogą automatycznie usuwać nieużywane lokalizacje i klucze. Importujesz wiadomości jako funkcje zamiast wyszukiwać je po kluczach tekstowych.) > - LinguiJS (Kompilator makr do funkcji, który przepisuje makra wiadomości, takie jak `<Trans>`, na zwykłe wywołania funkcji JS podczas budowania. Otrzymujesz składnię ICU/MessageFormat z bardzo małym narzutem w czasie wykonywania.) > - Lingo.dev (Skupia się na automatyzacji procesu lokalizacji poprzez wstrzykiwanie przetłumaczonej zawartości bezpośrednio podczas budowania aplikacji React. Może automatycznie generować tłumaczenia za pomocą AI i integrować się bezpośrednio z CI/CD.) > - Wuchale (Preprocesor skoncentrowany na Svelte, który wyodrębnia tekst inline w plikach .svelte i kompiluje go do funkcji tłumaczeniowych bez dodatkowych wrapperów. Unika kluczy tekstowych i całkowicie oddziela logikę ekstrakcji treści od głównego środowiska uruchomieniowego aplikacji.) > - Intlayer (Kompilator / CLI do ekstrakcji, który analizuje twoje komponenty, generuje typowane słowniki i opcjonalnie może przepisać kod, aby używać jawnej zawartości Intlayer. Celem jest wykorzystanie kompilatora dla szybkości, zachowując deklaratywne, niezależne od frameworka jądro.) > **Przykład deklaratywnego i18n:** > > - i18next / react-i18next / next-i18next (Dojrzały standard branżowy wykorzystujący słowniki JSON w czasie wykonywania oraz rozbudowany ekosystem wtyczek) > - react-intl (Część biblioteki FormatJS, skupiająca się na standardowej składni komunikatów ICU oraz ścisłym formatowaniu danych) > - next-intl (Specjalnie zoptymalizowany dla Next.js z integracją dla App Router i React Server Components) > - vue-i18n / @nuxt/i18n (Standardowe rozwiązanie ekosystemu Vue oferujące bloki tłumaczeń na poziomie komponentów oraz ścisłą integrację reaktywności) > - svelte-i18n (Lekka nakładka na Svelte stores dla reaktywnych tłumaczeń w czasie wykonywania) > - angular-translate (Przestarzała biblioteka dynamicznych tłumaczeń oparta na wyszukiwaniu kluczy w czasie wykonywania zamiast scalania podczas budowania) > - angular-i18n (Natywne podejście Angulara, działające ahead-of-time, scalające pliki XLIFF bezpośrednio z szablonami podczas budowania) > - Tolgee (Łączy deklaratywny kod z SDK w kontekście, umożliwiając edycję "kliknij, aby przetłumaczyć" bezpośrednio w interfejsie użytkownika) > - Intlayer (Podejście per-komponent, wykorzystujące pliki deklaracji treści umożliwiające natywne tree-shaking oraz walidację TypeScript) ## Kompilator Intlayer Chociaż **Intlayer** jest rozwiązaniem, które zasadniczo zachęca do **deklaratywnego podejścia** do Twoich treści, zawiera kompilator, który pomaga przyspieszyć rozwój lub ułatwić szybkie prototypowanie. Kompilator Intlayer przeszukuje AST (Abstract Syntax Tree) Twoich komponentów React, Vue lub Svelte, a także innych plików JavaScript/TypeScript. Jego rolą jest wykrywanie zakodowanych na stałe łańcuchów znaków i wyodrębnianie ich do dedykowanych deklaracji `.content`. > Aby uzyskać więcej szczegółów, zapoznaj się z dokumentacją: [Intlayer Compiler Docs](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/compiler.md) ## Urok Kompilatora (Podejście "Magiczne") Jest powód, dla którego to nowe podejście zyskuje na popularności. Dla dewelopera doświadczenie jest niesamowite. ### 1. Szybkość i "Flow" Kiedy jesteś w strefie, zatrzymanie się, aby wymyślić semantyczną nazwę zmiennej (`home_hero_title_v2`), przerywa twój flow. Przy podejściu kompilatora wpisujesz `<p>Welcome back</p>` i idziesz dalej. Tarcie jest zerowe. ### 2. Misja Ratunkowa dla Dziedzictwa (Legacy) Wyobraź sobie, że dziedziczysz ogromną bazę kodu z 5000 komponentami i zerowymi tłumaczeniami. Dostosowanie tego do ręcznego systemu opartego na kluczach to koszmar trwający miesiącami. Narzędzie oparte na kompilatorze działa jako strategia ratunkowa, natychmiast wyciągając tysiące ciągów znaków bez konieczności ręcznego dotykania pojedynczego pliku. ### 3. Era AI To nowoczesna korzyść, której nie powinniśmy pomijać. Asystenci kodowania AI (tacy jak Copilot czy ChatGPT) naturalnie generują standardowy JSX/HTML. Nie znają twojego specyficznego schematu kluczy tłumaczeń. - **Deklaratywne:** Musisz przepisać wynik AI, aby zastąpić tekst kluczami. - **Kompilator:** Kopiujesz i wklejasz kod AI i po prostu działa. ## Sprawdzenie rzeczywistości: Dlaczego „magia” jest niebezpieczna Chociaż „magia” jest kusząca, abstrakcja przecieka. Poleganie na narzędziu do budowania, które ma rozumieć intencje człowieka, wprowadza architektoniczną kruchość. ### Kruchość heurystyczna (gra w zgadywanie) Kompilator musi zgadywać, co jest treścią, a co kodem. Prowadzi to do sytuacji brzegowych, w których kończysz na „walce” z narzędziem. Rozważ te scenariusze: - Czy `<span className="active"></span>` jest wyodrębniane? (To jest string, ale prawdopodobnie klasa). - Czy `<span status="pending"></span>` jest wyodrębniane? (To jest wartość propsa). - Czy `<span>{"Hello World"}</span>` jest wyodrębniane? (To jest wyrażenie JS). - Czy `<span>Hello {name}. How are you?</span>` jest wyodrębniane? (Interpolacja jest skomplikowana). - Czy `<span aria-label="Image of cat"></span>` jest wyodrębniane? (Atrybuty dostępności wymagają tłumaczenia). - Czy `<span data-testid="my-element"></span>` jest wyodrębniany? (ID testów NIE powinny być tłumaczone). - Czy `<MyComponent errorMessage="An error occurred" />` jest wyodrębniany? - Czy `<p>This is a paragraph{" "}\n containing multiple lines</p>` jest wyodrębniany? - Czy wynik funkcji `<p>{getStatusMessage()}</p>` jest wyodrębniany? - Czy `<div>{isLoading ? "The page is loading" : <MyComponent/>} </div>` jest wyodrębniany? - Czy ID produktu takie jak `<span>AX-99</span>` jest wyodrębniany? Nieuchronnie kończysz na dodawaniu specyficznych komentarzy (np. `// ignore-translation` lub specyficznych atrybutów jak `data-compiler-ignore="true"`) aby zapobiec łamaniu logiki Twojej aplikacji. ### Jak Intlayer radzi sobie z tą złożonością? Intlayer używa podejścia mieszanego do wykrywania, czy pole powinno zostać wyodrębnione do tłumaczenia, starając się zminimalizować fałszywe trafienia: 1. **Analiza AST:** Sprawdza typ elementu (np. rozróżnia `reactNode`, `label` lub właściwość `title`). 2. **Rozpoznawanie wzorców:** Wykrywa, czy ciąg znaków jest napisany wielką literą lub zawiera spacje, co sugeruje, że jest to prawdopodobnie tekst czytelny dla człowieka, a nie identyfikator kodu. ### Twardy limit danych dynamicznych Ekstrakcja przez kompilator opiera się na **analizie statycznej**. Musi zobaczyć dosłowny ciąg znaków w Twoim kodzie, aby wygenerować stabilny identyfikator. Jeśli Twoje API zwraca ciąg znaków z kodem błędu, taki jak `server_error`, nie możesz go przetłumaczyć za pomocą kompilatora, ponieważ kompilator nie zna tego ciągu w czasie kompilacji. Jesteś zmuszony do zbudowania drugorzędnego systemu działającego wyłącznie w czasie wykonywania, przeznaczonego tylko dla danych dynamicznych. ### Brak dzielenia na fragmenty Niektóre kompilatory nie dzielą tłumaczeń na fragmenty na poziomie stron. Jeśli Twój kompilator generuje duży plik JSON na język (np. `./lang/en.json`, `./lang/fr.json` itd.), prawdopodobnie załadujesz zawartość ze wszystkich stron podczas odwiedzania jednej strony. Dodatkowo każdy komponent korzystający z Twoich treści zostanie prawdopodobnie zainicjowany z dużo większą ilością danych niż to konieczne, co może powodować problemy z wydajnością. Bądź również ostrożny przy dynamicznym ładowaniu tłumaczeń. Jeśli tego nie zrobisz, załadujesz zawartość dla wszystkich języków oprócz bieżącego. > Aby zobrazować problem, rozważ stronę z 10 podstronami i 10 językami (wszystkie w 100% unikalne). Załadujesz zawartość dla dodatkowych 99 podstron (10 × 10 - 1). ### „Eksplozja chunków” i wodospady sieciowe Aby rozwiązać problem chunkowania, niektóre rozwiązania oferują chunkowanie per komponent, a nawet per klucz. Jednak problem jest tylko częściowo rozwiązany. Głównym argumentem tych rozwiązań jest często stwierdzenie „Twoja zawartość jest tree-shaken”. Rzeczywiście, jeśli ładujesz zawartość statycznie, twoje rozwiązanie usunie nieużywaną zawartość (tree-shake), ale i tak skończysz z zawartością ze wszystkich języków załadowaną wraz z aplikacją. Więc dlaczego nie ładować go dynamicznie? Tak, w takim przypadku załadujesz więcej treści niż jest to konieczne, ale nie jest to pozbawione kompromisów. Dynamiczne ładowanie treści izoluje każdą część treści w osobnym kawałku (chunku), który będzie ładowany tylko wtedy, gdy komponent zostanie wyrenderowany. Oznacza to, że wykonasz jedno żądanie HTTP na każdy blok tekstu. 1000 bloków tekstu na Twojej stronie? → 1000 żądań HTTP do Twoich serwerów. Aby ograniczyć szkody i zoptymalizować czas pierwszego renderowania aplikacji, będziesz musiał wstawić wiele granic Suspense lub Skeleton Loaderów. > Uwaga: Nawet z Next.js i SSR, Twoje komponenty będą nadal hydradowane po załadowaniu, więc żądania HTTP nadal będą wykonywane. Rozwiązanie? Przyjęcie rozwiązania, które pozwala deklarować zakresowe deklaracje treści, tak jak robią to `i18next`, `next-intl` lub `intlayer`. > Uwaga: `i18next` i `next-intl` wymagają ręcznego zarządzania importami przestrzeni nazw / wiadomości dla każdej strony, aby zoptymalizować rozmiar pakietu. Powinieneś użyć analizatora pakietów, takiego jak `rollup-plugin-visualizer` (vite), `@next/bundle-analyzer` (next.js) lub `webpack-bundle-analyzer` (React CRA / Angular / itp.), aby wykryć, czy nie zaśmiecasz swojego pakietu nieużywanymi tłumaczeniami. ### Obciążenie wydajności w czasie działania Aby uczynić tłumaczenia reaktywnymi (tak, aby aktualizowały się natychmiast po zmianie języka), kompilator często wstrzykuje hooki zarządzania stanem do każdego komponentu. - **Koszt:** Jeśli renderujesz listę 5 000 elementów, inicjujesz 5 000 hooków `useState` i `useEffect` wyłącznie dla tekstu. React musi zidentyfikować i ponownie wyrenderować wszystkich 5 000 konsumentów jednocześnie. Powoduje to ogromne zablokowanie "Głównego Wątku", zamrażając interfejs użytkownika podczas przełączania. Zużywa to pamięć i cykle CPU, które oszczędzają biblioteki deklaratywne (które zazwyczaj używają pojedynczego dostawcy Context). > Uwaga: problematyka jest podobna w innych frameworkach niż React. ## Pułapka: Vendor Lock-in Uważaj, aby wybrać rozwiązanie i18n, które pozwala na ekstrakcję lub migrację kluczy tłumaczeń. W przypadku biblioteki deklaratywnej, Twój kod źródłowy wyraźnie zawiera zamiar tłumaczenia: to są Twoje klucze i masz nad nimi kontrolę. Jeśli chcesz zmienić bibliotekę, zazwyczaj wystarczy zaktualizować import. W podejściu kompilatora, Twój kod źródłowy może być po prostu zwykłym tekstem angielskim, bez śladu logiki tłumaczenia: wszystko jest ukryte w konfiguracji narzędzia budującego. Jeśli ten plugin przestanie być utrzymywany lub chcesz zmienić rozwiązanie, możesz utknąć. Nie ma łatwego sposobu na „wyjście”: w Twoim kodzie nie ma użytecznych kluczy i może być konieczne ponowne wygenerowanie wszystkich tłumaczeń dla nowej biblioteki. Niektóre rozwiązania oferują również usługi generowania tłumaczeń. Brak kredytów? Brak tłumaczeń. Kompilatory często haszują tekst (np. `"Hello World"` -> `x7f2a`). Twoje pliki tłumaczeń wyglądają wtedy tak: `{ "x7f2a": "Hola Mundo" }`. Pułapka: jeśli zmienisz bibliotekę, nowa biblioteka widzi `"Hello World"` i szuka tego klucza. Nie znajdzie go, ponieważ Twój plik tłumaczeń jest pełen haszy (`x7f2a`). ### Uzależnienie od Platformy Wybierając podejście oparte na kompilatorze, zamykasz się w podstawowej platformie. Na przykład, niektóre kompilatory nie są dostępne dla wszystkich bundlerów (takich jak Vite, Turbopack lub Metro). To może utrudnić przyszłe migracje i możesz potrzebować przyjąć wiele rozwiązań, aby pokryć wszystkie swoje aplikacje. ## Druga Strona: Ryzyka Podejścia Deklaratywnego Aby być sprawiedliwym, tradycyjny sposób deklaratywny też nie jest idealny. Ma swoje własne "pułapki". 1. **Piekło przestrzeni nazw:** Często musisz ręcznie zarządzać, które pliki JSON ładować (`common.json`, `dashboard.json`, `footer.json`). Jeśli zapomnisz o którymś, użytkownik zobaczy surowe klucze. 2. **Nadmierne pobieranie:** Bez ostrożnej konfiguracji bardzo łatwo jest przypadkowo załadować _wszystkie_ klucze tłumaczeń dla _wszystkich_ stron podczas początkowego ładowania, co powoduje nadmierne powiększenie rozmiaru paczki. 3. **Dryf synchronizacji:** Często zdarza się, że klucze pozostają w pliku JSON długo po usunięciu komponentu, który ich używał. Twoje pliki tłumaczeń rosną w nieskończoność, wypełnione "zombie kluczami". ## Środkowa droga Intlayer To właśnie tutaj narzędzia takie jak **Intlayer** próbują wprowadzać innowacje. Intlayer rozumie, że choć kompilatory są potężne, to ukryta magia jest niebezpieczna. Intlayer oferuje podejście mieszane, pozwalające korzystać z zalet obu metod: deklaratywnego zarządzania treścią, które jest również kompatybilne z jego kompilatorem, co oszczędza czas programowania. A nawet jeśli nie używasz kompilatora Intlayer, Intlayer oferuje polecenie `transform` (dostępne również za pomocą rozszerzenia VSCode). Zamiast wykonywać magię w ukrytym kroku budowania, faktycznie może **przepisać kod twojego komponentu**. Skanuje twój tekst i zastępuje go jawnie zadeklarowanymi treściami w twojej bazie kodu. Daje to najlepsze z obu światów: 1. **Szczegółowość:** Trzymasz tłumaczenia blisko swoich komponentów (poprawiając modularność i tree-shaking). 2. **Bezpieczeństwo:** Tłumaczenie staje się jawnie zapisanym kodem, a nie ukrytą magią podczas budowania. 3. **Brak uzależnienia:** Ponieważ kod jest przekształcany w deklaratywną strukturę w twoim repozytorium, możesz łatwo nacisnąć tabulator lub użyć copilot w IDE, aby generować deklaracje treści, nie ukrywając logiki w wtyczce webpack. ## Wnioski Więc, którą opcję powinieneś wybrać? **Jeśli tworzysz MVP lub chcesz działać szybko:** Podejście oparte na kompilatorze jest dobrym wyborem. Pozwala na niezwykle szybkie działanie. Nie musisz się martwić o strukturę plików czy klucze. Po prostu budujesz. Dług techniczny to problem dla „Przyszłego Ciebie”. **Jeśli jesteś Junior Developerem lub nie zależy Ci na optymalizacji:** Jeśli chcesz jak najmniej ręcznego zarządzania, podejście oparte na kompilatorze jest prawdopodobnie najlepsze. Nie będziesz musiał samodzielnie obsługiwać kluczy czy plików tłumaczeń — po prostu piszesz tekst, a kompilator automatyzuje resztę. To zmniejsza nakład pracy przy konfiguracji i typowe błędy i18n związane z ręcznymi krokami. **Jeśli internacjonalizujesz istniejący projekt, który już zawiera tysiące komponentów do refaktoryzacji:** Podejście oparte na kompilatorze może być tutaj pragmatycznym wyborem. Początkowa faza ekstrakcji może zaoszczędzić tygodnie lub miesiące ręcznej pracy. Jednak rozważ użycie narzędzia takiego jak polecenie `transform` Intlayer, które może wyodrębnić ciągi znaków i przekształcić je w jawne deklaracje treści deklaratywnej. Daje to szybkość automatyzacji przy jednoczesnym zachowaniu bezpieczeństwa i przenośności podejścia deklaratywnego. Otrzymujesz to, co najlepsze z obu światów: szybką początkową migrację bez długoterminowego długu architektonicznego. **Jeśli tworzysz profesjonalną aplikację klasy Enterprise:** Magia zazwyczaj jest złym pomysłem. Potrzebujesz kontroli. - Musisz obsługiwać dynamiczne dane z backendów. - Musisz zapewnić wydajność na urządzeniach o niskiej wydajności (unikając eksplozji hooków). - Musisz zapewnić, że nie zostaniesz na stałe związany z konkretnym narzędziem do budowania. Dla profesjonalnych aplikacji **Deklaratywne Zarządzanie Treścią** (takie jak Intlayer lub sprawdzone biblioteki) pozostaje złotym standardem. Oddziela to Twoje obszary odpowiedzialności, utrzymuje architekturę w czystości i zapewnia, że zdolność Twojej aplikacji do obsługi wielu języków nie zależy od „czarnej skrzynki” kompilatora, który zgaduje Twoje intencje.