Zadaj pytanie i otrzymaj streszczenie dokumentu, odwołując się do tej strony i wybranego dostawcy AI
Historia wersji
- "Aktualizacja użycia API useIntlayer w Solid do bezpośredniego dostępu do właściwości"v8.9.04.05.2026
- "Dodano dla Tanstack Start Solid.js"v8.5.125.03.2026
Treść tej strony została przetłumaczona przy użyciu sztucznej inteligencji.
Zobacz ostatnią wersję oryginalnej treści w języku angielskimJeśli masz pomysł na ulepszenie tej dokumentacji, zachęcamy do przesłania pull requesta na GitHubie.
Link do dokumentacji na GitHubieKopiuj dokument Markdown do schowka
Przetłumacz swoją stronę Tanstack Start + Solid.js za pomocą Intlayer | Internacjonalizacja (i18n)
Spis treści
Ten przewodnik pokazuje, jak zintegrować Intlayer w celu zapewnienia bezproblemowej internacjonalizacji w projektach Tanstack Start z Solid.js, z routingiem uwzględniającym lokalizację, wsparciem TypeScript oraz nowoczesnymi praktykami programistycznymi.
Dlaczego Interlayer zamiast alternatyw?
W porównaniu do głównych rozwiązań, takich jak „react-i18next” lub „i18next”, Intlayer jest rozwiązaniem wyposażonym w zintegrowane optymalizacje, takie jak:
Pełne pokrycie TanStack Start
Intlayer jest zoptymalizowany do doskonałej współpracy z TanStack Start i Solid, oferując routing wielojęzyczny, mapę witryny i wszystkie funkcje potrzebne do skalowania internacjonalizacji (i18n).
Rozmiar bundle'a
Zamiast ładować ogromne pliki JSON na swoje strony, ładuj tylko niezbędną treść. Intlayer pomaga zmniejszyć rozmiary bundle'a i stron nawet o 50%.
Łatwość konserwacji
Określanie zakresu zawartości aplikacji ułatwia konserwację aplikacji na dużą skalę. Możesz powielić lub usunąć pojedynczy folder funkcji bez obciążania psychicznego koniecznością przeglądania całej bazy kodu zawartości. Dodatkowo Inlayer jest w pełni napisany, aby zapewnić dokładność treści.
Agent AI
Wspólna lokalizacja treści zmniejsza potrzebny kontekst dzięki modelom dużego języka (LLM). Intlayer zawiera także zestaw narzędzi, taki jak CLI do sprawdzania brakujących tłumaczeńLSP, MCP i umiejętności agenta, aby praca programisty (DX) była jeszcze płynniejsza dla agentów AI.
Automatyzacja
Korzystaj z automatyzacji, aby tłumaczyć w swoim potoku CI/CD przy użyciu wybranego LLM na koszt dostawcy sztucznej inteligencji. Intlayer oferuje także kompilator do automatyzacji ekstrakcji treści, a także [platformę internetową] (/pl/doc/concept/cms), która pomaga tłumaczyć w tle.
Wydajność
Łączenie ogromnych plików JSON z komponentami może prowadzić do problemów z wydajnością i reaktywnością. Inlayer optymalizuje ładowanie treści w czasie kompilacji.
Skalowanie bez użycia dewelopera
Więcej niż tylko rozwiązanie i18n, Intlayer zapewnia samodzielny edytor wizualny i pełny CMS, który pomoże Ci zarządzać wielojęzyczną treścią w w czasie rzeczywistym, dzięki czemu współpraca z tłumaczami, copywriterami i innymi członkami zespołu będzie płynna. Treść może być przechowywana lokalnie i/lub zdalnie.
Przewodnik krok po kroku dotyczący konfiguracji Intlayer w aplikacji Tanstack Start
Zobacz Szablon Aplikacji na GitHubie.
Utworzenie projektu
Najpierw utwórz nowy projekt TanStack Start, postępując zgodnie z przewodnikiem Rozpoczęcie nowego projektu na stronie TanStack Start.
Instalacja pakietów Intlayer
Zainstaluj niezbędne pakiety za pomocą preferowanego menedżera pakietów:
bashKopiuj kodSkopiuj kod do schowka
intlayer
Rdzeń pakietu, który dostarcza narzędzia internacjonalizacji do zarządzania konfiguracją, tłumaczeniami, deklaracją treści, transpilacją oraz poleceniami CLI.
solid-intlayer Pakiet integrujący Intlayer z aplikacją Solid. Dostarcza dostawców kontekstu (context providers) i hooki do internacjonalizacji w Solid.
vite-intlayer Zawiera wtyczkę Vite do integracji Intlayer z bundlerem Vite, a także middleware do wykrywania preferowanego języka użytkownika, zarządzania ciasteczkami (cookies) i obsługi przekierowań adresów URL.
Konfiguracja Twojego projektu
Utwórz plik konfiguracyjny, aby ustawić języki Twojej aplikacji:
intlayer.config.tsKopiuj kodSkopiuj kod do schowka
Za pomocą tego pliku konfiguracyjnego możesz skonfigurować zlokalizowane adresy URL, przekierowania middleware, nazwy ciasteczek, lokalizację i rozszerzenie deklaracji treści, wyłączyć logi Intlayer w konsoli i wiele więcej. Pełną listę dostępnych parametrów znajdziesz w dokumentacji konfiguracji.
Integracja Intlayer w konfiguracji Vite
Dodaj wtyczkę intlayer do swojej konfiguracji:
vite.config.tsKopiuj kodSkopiuj kod do schowka
Wtyczka
intlayer()Vite jest używana do integracji Intlayer z Vite. Zapewnia ona budowanie plików deklaracji treści i monitoruje je w trybie deweloperskim. Definiuje ona zmienne środowiskowe Intlayer wewnątrz aplikacji Vite. Dodatkowo zapewnia aliasy w celu zmniejszenia narzutu wydajnościowego.Utworzenie Root Layoutu
Skonfiguruj swój layout główny (root layout), aby obsługiwał internacjonalizację, używając
useParamsdo wykrywania bieżącego języka i ustawiając atrybutylangorazdirw taguhtml.src/routes/__root.tsxKopiuj kodSkopiuj kod do schowka
Utworzenie Layoutu Językowego
Utwórz layout, który obsługuje prefiks językowy i wykonuje walidację. Ten layout zapewni, że przetwarzane będą tylko prawidłowe języki.
Ten krok jest opcjonalny, jeśli nie potrzebujesz walidacji prefiksu języka na poziomie trasy.
src/routes/{-$locale}/route.tsxKopiuj kodSkopiuj kod do schowka
Tutaj
{-$locale}jest dynamicznym parametrem trasy, który jest zastępowany przez aktualny język. Ta notacja sprawia, że slot jest opcjonalny, co pozwala na współpracę z trybami routingu takimi jak'prefix-no-default'itp.Bądź świadomy, że ten slot może powodować problemy, jeśli używasz wielu dynamicznych segmentów w tej samej trasie (np.:
/{-$locale}/other-path/$anotherDynamicPath/...). Dla trybu'prefix-all'możesz preferować zamianę slotu na$locale. Dla trybu'no-prefix'lub'search-params'możesz całkowicie usunąć ten slot.Zadeklaruj swoją treść
Twórz i zarządzaj swoimi deklaracjami treści, aby przechowywać tłumaczenia:
src/contents/page.content.tsKopiuj kodSkopiuj kod do schowka
Twoje deklaracje treści mogą być definiowane w dowolnym miejscu w aplikacji, pod warunkiem, że znajdują się w katalogu
contentDir(domyślnie./app) i pasują do rozszerzenia pliku deklaracji treści (domyślnie.content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).Więcej szczegółów znajdziesz w dokumentacji deklaracji treści.
Wykorzystaj komponenty i hooki uwzględniające lokalizację
Utwórz komponent
LocalizedLinkdo nawigacji uwzględniającej język:src/components/LocalizedLink.tsxKopiuj kodSkopiuj kod do schowka
Ten komponent służy dwóm celom:
- Usuwaniu niepotrzebnego prefiksu
{-$locale}z adresu URL. - Wstrzykiwaniu parametru lokalizacji do adresu URL, aby upewnić się, że użytkownik zostanie bezpośrednio przekierowany na zlokalizowaną trasę.
Następnie możemy utworzyć hook
useLocalizedNavigatedo nawigacji programowej:src/hooks/useLocalizedNavigate.tsxKopiuj kodSkopiuj kod do schowka
- Usuwaniu niepotrzebnego prefiksu
Użyj Intlayer na swoich stronach
Zyskaj dostęp do słowników treści w całej aplikacji:
Zlokalizowana Strona Główna
src/routes/{-$locale}/index.tsxKopiuj kodSkopiuj kod do schowka
Jeśli chcesz użyć swojej zawartości w atrybucie typu
string, takim jakalt,title,href,aria-labelitp., musisz wywołać wartość funkcji, na przykład:htmlKopiuj kodSkopiuj kod do schowka
In Solid,
useIntlayerreturns reactive content (e.g.,content). You can access its properties directly.Aby dowiedzieć się więcej o hooku
useIntlayer, zapoznaj się z dokumentacją.Utworzenie komponentu Locale Switcher
Utwórz komponent pozwalający użytkownikom na zmianę języka:
src/components/LocaleSwitcher.tsxKopiuj kodSkopiuj kod do schowka
W plikach Solid,
localezuseLocaleto signal accessor. Użyjlocale()(z nawiasami), aby reaktywnie odczytać jego aktualną wartość.Aby dowiedzieć się więcej o hooku
useLocale, zapoznaj się z dokumentacją.Zarządzanie atrybutami HTML
Jak pokazano w Kroku 5, możesz zarządzać atrybutami
langorazdirtaguhtmlza pomocąuseParamsw swoim głównym komponencie (root component). Dzięki temu prawidłowe atrybuty zostaną ustawione zarówno na serwerze, jak i na kliencie.src/routes/__root.tsxKopiuj kodSkopiuj kod do schowka
Dodaj Middleware
Możesz również użyć
intlayerProxy, aby dodać routing po stronie serwera do swojej aplikacji. Ten plugin automatycznie wykryje aktualny język na podstawie adresu URL i ustawi odpowiednie ciasteczko (cookie) języka. Jeśli nie określono języka, plugin określi najbardziej odpowiedni na podstawie preferencji językowych przeglądarki użytkownika. Jeśli nie zostanie wykryty żaden język, nastąpi przekierowanie do domyślnego języka.Zauważ, że aby korzystać z
intlayerProxyw środowisku produkcyjnym, musisz przenieść pakietvite-intlayerzdevDependenciesdodependencies.vite.config.tsKopiuj kodSkopiuj kod do schowka
Umiędzynarowienie metadanych
Możesz również użyć funkcji
getIntlayer, aby uzyskać dostęp do swoich słowników treści wewnątrz loaderaheadw celu uzyskania metadanych uwzględniających lokalizację:src/routes/{-$locale}/index.tsxKopiuj kodSkopiuj kod do schowka
Pobieranie języka w akcjach serwera
Możesz chcieć uzyskać dostęp do bieżącego języka wewnątrz akcji serwera (server actions) lub punktów końcowych API. Możesz to zrobić, używając pomocnika
getLocalezintlayer.Oto przykład użycia funkcji serwerowych TanStack Start:
src/routes/{-$locale}/index.tsxKopiuj kodSkopiuj kod do schowka
Zarządzanie stronami "nie znaleziono" (404)
OpcjonalneGdy użytkownik odwiedzi nieistniejącą stronę, możesz wyświetlić niestandardową stronę 404, a prefiks językowy może wpływać na sposób wyzwalania strony 404.
Zrozumienie obsługi 404 w TanStack Router z prefiksami językowymi
W TanStack Router obsługa stron 404 ze zlokalizowanymi trasami wymaga podejścia wielowarstwowego:
- Dedykowana trasa 404: Specyficzna trasa do wyświetlania interfejsu 404
- Walidacja na poziomie trasy: Sprawdza prefiksy języka i przekierowuje nieprawidłowe na stronę 404
- Trasa catch-all: Przechwytuje wszystkie niepasujące ścieżki wewnątrz segmentu językowego
src/routes/{-$locale}/404.tsxKopiuj kodSkopiuj kod do schowka
src/routes/{-$locale}/route.tsxKopiuj kodSkopiuj kod do schowka
src/routes/{-$locale}/$.tsxKopiuj kodSkopiuj kod do schowka
Wyodrębnij treść ze swoich komponentów
OpcjonalneJeśli masz istniejącą bazę kodu, transformacja tysięcy plików może być czasochłonna.
Aby ułatwić ten proces, Intlayer proponuje kompilator / ekstraktor do transformacji komponentów i wyodrębnienia treści.
Aby go skonfigurować, możesz dodać sekcję
compilerw plikuintlayer.config.ts:intlayer.config.tsKopiuj kodSkopiuj kod do schowka
import { type IntlayerConfig } from "intlayer"; const config: IntlayerConfig = { // ... Reszta Twojej konfiguracji compiler: { /** * Wskazuje, czy kompilator powinien być włączony. */ enabled: true, /** * Definiuje ścieżkę plików wyjściowych */ output: ({ fileName, extension }) => `./${fileName}${extension}`, /** * Wskazuje, czy komponenty powinny zostać zapisane po transformacji. * * - Jeśli `true`, kompilator nadpisze plik komponentu na dysku. W ten sposób transformacja będzie trwała, a kompilator pominie transformację przy następnym procesie. W ten sposób kompilator może przetransformować aplikację, a następnie można go usunąć. * * - Jeśli `false`, kompilator wstrzyknie wywołanie funkcji `useIntlayer()` do kodu tylko w danych wyjściowych buildu, zachowując bazową bazę kodu nienaruszoną. Transformacja zostanie wykonana tylko w pamięci. */ saveComponents: false, /** * Prefiks klucza słownika */ dictionaryKeyPrefix: "", }, }; export default config;Uruchom ekstraktor, aby przetransformować swoje komponenty i wyodrębnić treść
bashKopiuj kodSkopiuj kod do schowka
Skonfiguruj TypeScript
Intlayer używa rozszerzania modułów (module augmentation), aby czerpać korzyści z TypeScript i wzmocnić Twoją bazę kodu.
Upewnij się, że Twoja konfiguracja TypeScript zawiera automatycznie generowane typy:
tsconfig.jsonKopiuj kodSkopiuj kod do schowka
Konfiguracja Git
Zaleca się ignorowanie plików generowanych przez Intlayer. Pozwala to uniknąć zakomitowania ich do repozytorium Git.
Aby to zrobić, możesz dodać następujące instrukcje do pliku .gitignore:
Skopiuj kod do schowka
Rozszerzenie VS Code
Aby poprawić swoje doświadczenia deweloperskie z Intlayer, możesz zainstalować oficjalne rozszerzenie Intlayer VS Code.
Zainstaluj z VS Code Marketplace
To rozszerzenie oferuje:
- Autouzupełnianie kluczy tłumaczeń.
- Wykrywanie błędów w czasie rzeczywistym dla brakujących tłumaczeń.
- Podgląd wewnątrz linii (inline previews) przetłumaczonej treści.
- Szybkie akcje do łatwego tworzenia i aktualizowania tłumaczeń.
Więcej szczegółów na temat korzystania z rozszerzenia znajdziesz w dokumentacji rozszerzenia Intlayer VS Code.
Idąc dalej
Aby pójść dalej, możesz zaimplementować edytor wizualny lub wyeksportować swoją treść za pomocą CMS.