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
- "Dodaj polecenie init"v7.5.930.12.2025
- "Zaktualizuj Layout i obsłuż 404"v7.5.627.12.2025
- "Zaktualizowano dokumentację"v6.1.53.10.2025
- "Dodano dla React Router v7"v5.8.24.09.2025
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ę React Router v7 za pomocą Intlayer | Internacjonalizacja (i18n)
Ten przewodnik pokazuje, jak zintegrować Intlayer dla płynnej internacjonalizacji w projektach React Router v7 z routingiem uwzględniającym lokalizację, wsparciem TypeScript oraz nowoczesnymi praktykami programistycznymi.
Table of Contents
Czym jest Intlayer?
Intlayer to innowacyjna, otwartoźródłowa biblioteka do internacjonalizacji (i18n), zaprojektowana, aby uprościć wsparcie wielojęzyczne w nowoczesnych aplikacjach webowych.
Dzięki Intlayer możesz:
- Łatwo zarządzać tłumaczeniami za pomocą deklaratywnych słowników na poziomie komponentów.
- Dynamicznie lokalizować metadane, trasy i zawartość.
- Zapewnić wsparcie TypeScript dzięki automatycznie generowanym typom, co poprawia autouzupełnianie i wykrywanie błędów.
- Korzystaj z zaawansowanych funkcji, takich jak dynamiczne wykrywanie i przełączanie lokalizacji.
- Włącz routing uwzględniający lokalizację za pomocą systemu routingu opartego na konfiguracji w React Router v7.
Przewodnik krok po kroku, jak skonfigurować Intlayer w aplikacji React Router v7
Krok 1: Zainstaluj zależności
Zainstaluj niezbędne pakiety, używając preferowanego menedżera pakietów:
Skopiuj kod do schowka
npm install intlayer react-intlayernpm install vite-intlayer --save-devnpx intlayer initintlayer
Główny pakiet, który dostarcza narzędzia do internacjonalizacji, zarządzania konfiguracją, tłumaczeń, deklaracji treści, transpilecji oraz poleceń CLI.
react-intlayer Pakiet integrujący Intlayer z aplikacją React. Zapewnia dostawców kontekstu oraz hooki do internacjonalizacji w React.
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 oraz obsługi przekierowań URL.
Krok 2: Konfiguracja Twojego projektu
Przewodnik krok po kroku dotyczący konfiguracji Intlayer w aplikacji React Router v7 z trasami opartymi na systemie plików
See Application Template on GitHub.
Utwórz plik konfiguracyjny, aby skonfigurować języki swojej aplikacji:
Skopiuj kod do schowka
import { type IntlayerConfig, Locales } from "intlayer";
const config: IntlayerConfig = {
internationalization: {
defaultLocale: Locales.ENGLISH,
locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
},
};
export default config;Za pomocą tego pliku konfiguracyjnego możesz ustawić lokalizowane adresy URL, przekierowania w middleware, nazwy ciasteczek, lokalizację i rozszerzenie deklaracji zawartości, wyłączyć logi Intlayer w konsoli i wiele więcej. Pełną listę dostępnych parametrów znajdziesz w dokumentacji konfiguracyjnej.
Krok 3: Integracja Intlayer w konfiguracji Vite
Dodaj wtyczkę intlayer do swojej konfiguracji:
Skopiuj kod do schowka
import { reactRouter } from "@react-router/dev/vite";import { defineConfig } from "vite";import { intlayer } from "vite-intlayer";export default defineConfig({ plugins: [reactRouter(), intlayer()],});Wtyczka Vite intlayer() służy do integracji Intlayer z Vite. Zapewnia budowanie plików deklaracji zawartości i monitoruje je w trybie deweloperskim. Definiuje zmienne środowiskowe Intlayer w aplikacji Vite. Dodatkowo dostarcza aliasy w celu optymalizacji wydajności.
Krok 4: Konfiguracja tras React Router v7
Skonfiguruj routing z trasami uwzględniającymi lokalizację:
Skopiuj kod do schowka
import { layout, route, type RouteConfig } from "@react-router/dev/routes";export default [ route("/:lang?", "routes/page.tsx"), // Lokalizowana strona główna route("/:lang?/about", "routes/about/page.tsx"), // Lokalizowana strona o nas] satisfies RouteConfig;Krok 5: Tworzenie komponentów layoutu
Skonfiguruj swój główny layout oraz layouty specyficzne dla lokalizacji:
Główny Layout
Skopiuj kod do schowka
import { getLocaleFromPath } from "intlayer";import { IntlayerProvider } from "react-intlayer";import { data, Meta, Scripts, ScrollRestoration, useLoaderData,} from "react-router";import type { Route } from "./+types/root";// ... Unchanged App, links and ErrorBoundary codeexport async function loader({ request }: Route.LoaderArgs) { const locale = getLocaleFromPath(request.url); if (!locale) { throw data("Language not supported", { status: 404 }); } return { locale };}export function Layout({ children,}: { children: React.ReactNode } & Route.ComponentProps) { const data = useLoaderData<typeof loader>(); const { locale } = data ?? {}; return ( <html lang={locale}> <head> <meta charSet="utf-8" /> <meta content="width=device-width, initial-scale=1" name="viewport" /> <Meta /> <Links /> </head> <body> <IntlayerProvider locale={locale}>{children}</IntlayerProvider> <ScrollRestoration /> <Scripts /> </body> </html> );}Krok 6: Zadeklaruj swoją zawartość
Utwórz i zarządzaj deklaracjami zawartości, aby przechowywać tłumaczenia:
Skopiuj kod do schowka
import { t, type Dictionary } from "intlayer";const pageContent = { key: "page", content: { title: t({ en: "Welcome to React Router v7 + Intlayer", es: "Bienvenido a React Router v7 + Intlayer", fr: "Bienvenue sur React Router v7 + Intlayer", }), description: t({ en: "Build multilingual applications with ease using React Router v7 and Intlayer.", pl: "Twórz wielojęzyczne aplikacje z łatwością, korzystając z React Router v7 i Intlayer.", es: "Cree aplicaciones multilingües fácilmente usando React Router v7 y Intlayer.", fr: "Créez des applications multilingues facilement avec React Router v7 et Intlayer.", }), aboutLink: t({ en: "Learn About Us", pl: "Dowiedz się o nas", es: "Aprender Sobre Nosotros", fr: "En savoir plus sur nous", }), homeLink: t({ en: "Home", pl: "Strona główna", es: "Inicio", fr: "Accueil", }), },} satisfies Dictionary;export default pageContent;Twoje deklaracje treści mogą być zdefiniowane w dowolnym miejscu w aplikacji, pod warunkiem, że zostaną umieszczone w katalogucontentDir(domyślnie./app). I muszą odpowiadać rozszerzeniu pliku deklaracji treści (domyślnie.content.{json,ts,tsx,js,jsx,mjs,cjs}).
Po więcej szczegółów odsyłamy do dokumentacji deklaracji treści.
Krok 7: Tworzenie komponentów uwzględniających lokalizację
Utwórz komponent LocalizedLink do nawigacji uwzględniającej lokalizację:
Skopiuj kod do schowka
import type { FC } from "react";import { getLocalizedUrl, type LocalesValues } from "intlayer";import { useLocale } from "react-intlayer";import { Link, type LinkProps, type To } from "react-router";const isExternalLink = (to: string) => /^(https?:)?\/\//.test(to);// Funkcja lokalizująca ścieżkę na podstawie podanego localeexport const locacalizeTo = (to: To, locale: LocalesValues): To => { if (typeof to === "string") { if (isExternalLink(to)) { return to; // Zwraca link zewnętrzny bez zmian } return getLocalizedUrl(to, locale); // Zwraca lokalizowany URL } if (isExternalLink(to.pathname ?? "")) { return to; // Zwraca link zewnętrzny bez zmian } return { ...to, pathname: getLocalizedUrl(to.pathname ?? "", locale), // Lokalizuje pathname };};// Komponent linku lokalizowanegoexport const LocalizedLink: FC<LinkProps> = (props) => { const { locale } = useLocale(); return <Link {...props} to={locacalizeTo(props.to, locale)} />;};W przypadku, gdy chcesz nawigować do lokalizowanych tras, możesz użyć hooka useLocalizedNavigate:
Skopiuj kod do schowka
import { useLocale } from "react-intlayer";import { type NavigateOptions, type To, useNavigate } from "react-router";import { locacalizeTo } from "~/components/localized-link";export const useLocalizedNavigate = () => { const navigate = useNavigate(); const { locale } = useLocale(); const localizedNavigate = (to: To, options?: NavigateOptions) => { const localedTo = locacalizeTo(to, locale); navigate(localedTo, options); }; return localizedNavigate;};Krok 8: Wykorzystaj Intlayer na swoich stronach
Uzyskaj dostęp do swoich słowników treści w całej aplikacji:
Lokalizowana strona główna
Skopiuj kod do schowka
import { useIntlayer } from "react-intlayer";import { LocalizedLink } from "~/components/localized-link";export default function Page() { const { title, description, aboutLink } = useIntlayer("page"); return ( <div> <h1>{title}</h1> <p>{description}</p> <nav> <LocalizedLink to="/about">{aboutLink}</LocalizedLink> </nav> </div> );}Aby dowiedzieć się więcej o hooku useIntlayer, zapoznaj się z dokumentacją.
Jeśli Twoja aplikacja już istnieje, możesz użyć Intlayer Compiler w połączeniu z poleceniem extract, aby przekonwertować tysiące komponentów w jedną sekundę.
Krok 9: Utwórz komponent przełącznika języka
Utwórz komponent, który pozwoli użytkownikom zmieniać języki:
Skopiuj kod do schowka
import type { FC } from "react";import { getHTMLTextDir, getLocaleName, getLocalizedUrl, getPathWithoutLocale, Locales,} from "intlayer";import { setLocaleInStorage, useIntlayer, useLocale } from "react-intlayer";import { Link, useLocation } from "react-router";export const LocaleSwitcher: FC = () => { const { localeSwitcherLabel } = useIntlayer("locale-switcher"); const { pathname } = useLocation(); const { availableLocales, locale } = useLocale(); const pathWithoutLocale = getPathWithoutLocale(pathname); return ( <ol> {availableLocales.map((localeItem) => ( <li key={localeItem}> <Link aria-current={localeItem === locale ? "page" : undefined} aria-label={`${localeSwitcherLabel.value} ${getLocaleName(localeItem)}`} onClick={() => setLocale(localeItem)} to={getLocalizedUrl(pathWithoutLocale, localeItem)} > <span> {/* Lokalizacja - np. FR */} {localeItem} </span> <span> {/* Język w jego własnej lokalizacji - np. Français */} {getLocaleName(localeItem, locale)} </span> <span dir={getHTMLTextDir(localeItem)} lang={localeItem}> {/* Język w bieżącej lokalizacji - np. Francés przy ustawionej lokalizacji Locales.SPANISH */} {getLocaleName(localeItem)} </span> <span dir="ltr" lang={Locales.ENGLISH}> {/* Język po angielsku - np. French */} {getLocaleName(localeItem, Locales.ENGLISH)} </span> </Link> </li> ))} </ol> );};Aby dowiedzieć się więcej o hooku useLocale, zapoznaj się z dokumentacją.
Krok 10: Dodaj zarządzanie atrybutami HTML (opcjonalnie)
Utwórz hook do zarządzania atrybutami lang i dir w HTML:
Skopiuj kod do schowka
import { getHTMLTextDir } from "intlayer";import { useEffect } from "react";import { useLocale } from "react-intlayer";export const useI18nHTMLAttributes = () => { const { locale } = useLocale(); useEffect(() => { document.documentElement.lang = locale; document.documentElement.dir = getHTMLTextDir(locale); }, [locale]);};Następnie użyj go w swoim komponencie root:
Skopiuj kod do schowka
import { Outlet } from "react-router";import { IntlayerProvider } from "react-intlayer";import { useI18nHTMLAttributes } from "app/hooks/useI18nHTMLAttributes"; // importuj hookexport default function RootLayout() { useI18nHTMLAttributes(); // wywołaj hook return ( <IntlayerProvider> <Outlet /> </IntlayerProvider> );}(Opcjonalnie) Krok 12 : Wyodrębnij zawartość swoich komponentów
Jeś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, aby przetransformować komponenty i wyodrębnić zawartość.
Aby go skonfigurować, możesz dodać sekcję compiler w pliku intlayer.config.ts:
Skopiuj 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. W ten sposób kompilator można uruchomić tylko raz, aby przetransformować aplikację, a następnie go usunąć.
*/
saveComponents: false,
/**
* Prefiks klucza słownika
*/
dictionaryKeyPrefix: "",
},
};
export default config;Uruchom ekstraktor, aby przetransformować komponenty i wyodrębnić zawartość
Skopiuj kod do schowka
npx intlayer extractConfigure TypeScript
Intlayer uses module augmentation to get benefits of TypeScript and make your codebase stronger.
Ensure your TypeScript configuration includes the autogenerated types:
Skopiuj kod do schowka
{ // ... your existing configurations include: [ // ... your existing includes ".intlayer/**/*.ts", // Include the auto-generated types ],}Git Configuration
It is recommended to ignore the files generated by Intlayer. This allows you to avoid committing them to your Git repository.
To do this, you can add the following instructions to your .gitignore file:
Skopiuj kod do schowka
# Ignore the files generated by Intlayer.intlayerVS Code Extension
To improve your development experience with Intlayer, you can install the official Intlayer VS Code Extension.
Install from the VS Code Marketplace
This extension provides:
- Autocompletion for translation keys.
- Real-time error detection for missing translations.
- Inline previews of translated content.
- Quick actions to easily create and update translations.
For more details on how to use the extension, refer to the Intlayer VS Code Extension documentation.
Go Further
To go further, you can implement the visual editor or externalize your content using the CMS.
Documentation References
- Intlayer Documentation
- React Router v7 Documentation
- useIntlayer hook
- useLocale hook
- Content Declaration
- Configuration
This comprehensive guide provides everything you need to integrate Intlayer with React Router v7 for a fully internationalized application with locale-aware routing and TypeScript support.
Krok 11: Dodaj middleware (opcjonalnie)
Możesz również użyć intlayerProxy, aby dodać routing po stronie serwera do swojej aplikacji. Ten plugin automatycznie wykryje aktualny locale na podstawie URL i ustawi odpowiedni cookie locale. Jeśli locale nie jest określone, plugin wybierze najbardziej odpowiedni locale na podstawie preferencji językowych przeglądarki użytkownika. Jeśli nie zostanie wykryty żaden locale, nastąpi przekierowanie do domyślnego locale.
Zauważ, że aby używaćintlayerProxyw produkcji, musisz przenieść pakietvite-intlayerzdevDependenciesdodependencies.
Skopiuj kod do schowka
import { reactRouter } from "@react-router/dev/vite";import { defineConfig } from "vite";import { intlayer, intlayerProxy } from "vite-intlayer";export default defineConfig({ plugins: [ intlayerProxy(), // should be placed first reactRouter(), intlayer(), ],});Konfiguracja TypeScript
Intlayer wykorzystuje rozszerzanie modułów (module augmentation), aby korzystać z zalet TypeScript i wzmocnić Twoją bazę kodu.
Upewnij się, że Twoja konfiguracja TypeScript zawiera automatycznie generowane typy:
Skopiuj kod do schowka
{ // ... twoje istniejące konfiguracje include: [ // ... twoje istniejące dołączenia ".intlayer/**/*.ts", // Uwzględnij automatycznie generowane typy ],}Konfiguracja Git
Zaleca się ignorowanie plików generowanych przez Intlayer. Pozwala to uniknąć ich zatwierdzania do repozytorium Git.
Aby to zrobić, możesz dodać następujące instrukcje do pliku .gitignore:
Skopiuj kod do schowka
# Ignoruj pliki generowane przez Intlayer.intlayerRozszerzenie VS Code
Aby poprawić doświadczenie programistyczne z Intlayer, możesz zainstalować oficjalne rozszerzenie Intlayer dla 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ądy w linii przetłumaczonej zawartości.
- Szybkie akcje umożliwiające łatwe tworzenie i aktualizację tłumaczeń.
Aby uzyskać więcej informacji na temat korzystania z rozszerzenia, zapoznaj się z dokumentacją rozszerzenia Intlayer VS Code.
Idź dalej
Aby pójść dalej, możesz zaimplementować edytor wizualny lub wyodrębnić swoją zawartość, korzystając z CMS.
Odnośniki do dokumentacji
- Dokumentacja Intlayer
- Dokumentacja React Router v7
- useIntlayer hook
- useLocale hook
- Deklaracja treści
- Konfiguracja
Ten kompleksowy przewodnik zawiera wszystko, co potrzebne do integracji Intlayer z React Router v7, aby uzyskać w pełni zinternacjonalizowaną aplikację z trasowaniem uwzględniającym lokalizację oraz wsparciem dla TypeScript.