Przetłumacz swoją witrynę Astro + React za pomocą Intlayer

Spis treści

Dlaczego Interlayer zamiast alternatyw?

W porównaniu do głównych rozwiązań, takich jak „astro-i18n” czy „i18next”, Intlayer jest rozwiązaniem wyposażonym w zintegrowane optymalizacje, takie jak:

Przewodnik krok po kroku po konfiguracji Intlayer w Astro + React

Sprawdź szablon aplikacji na GitHubie.

1. 1

   Zainstaluj zależności

   Zainstaluj niezbędne pakiety za pomocą preferowanego menedżera pakietów:

   bash

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   npx intlayer init --interactive
   

   flaga --interactive jest opcjonalna. Użyj intlayer-cli init, jeśli jesteś agentem AI.

   To polecenie wykryje Twoje środowisko i zainstaluje wymagane pakiety. Na przykład:

   bash

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   npm install intlayer astro-intlayer react react-dom react-intlayer @astrojs/react
   

   • intlayer Główny pakiet zapewniający narzędzia i18n do zarządzania konfiguracją, tłumaczeniami, deklaracją treści, transpilacją i poleceniami CLI.

   • astro-intlayer Zawiera wtyczkę integracji z Astro do łączenia Intlayer z bundlerem Vite, middleware rozpoznające ustawienia regionalne każdego żądania w Astro.locals.intlayer oraz hooki useIntlayer / useDictionary / useLocale. Ta sama ścieżka importu prowadzi do implementacji serwerowej w nagłówku .astro oraz klienckiej (opartej na vanilla-intlayer) w blokach <script>.

   • react, react-dom Podstawowe pakiety React używane do renderowania komponentów React w przeglądarce.

   • react-intlayer Pakiet do integracji Intlayer z aplikacjami React. Zapewnia IntlayerProvider oraz hooki useIntlayer i useLocale dla międzynarodowości w React.

   • @astrojs/react Oficjalna integracja Astro pozwalająca na używanie islandów komponentów React.

2. 2

   Skonfiguruj swój projekt

   Architektura

   W tej architekturze integracja intlayer() zarejestrowana w astro.config.ts buduje Twoje słowniki i dodaje middleware, który rozwiązuje locale każdego żądania i udostępnia je w Astro.locals.intlayer. Strony znajdują się w segmencie rest src/pages/[...locale]/, dzięki czemu domyślne locale jest serwowane bez prefiksu, a każde inne locale otrzymuje własny dedykowany adres URL. Pliki .astro odczytują zawartość za pomocą hooków useIntlayer / useLocale z astro-intlayer do renderowania po stronie serwera, a wyspa React (src/components/react/ReactIsland.tsx) otrzymuje wykryte przez serwer locale jako prop i przekazuje je do react-intlayer dla części interaktywnej. Deklaracje zawartości są umieszczane obok Twoich komponentów w src/.

   bash

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   .
   ├── src
   │   ├── app.content.tsx               # App content declaration
   │   ├── components
   │   │   └── react
   │   │       ├── LocaleSwitcher.tsx    # Locale switcher rendered inside the island
   │   │       └── ReactIsland.tsx       # React island wrapping the tree in IntlayerProvider
   │   └── pages
   │       ├── [...locale]
   │       │   └── index.astro           # Localized page mounting the island
   │       ├── robots.txt.ts             # robots.txt endpoint
   │       └── sitemap.xml.ts            # Localized sitemap endpoint
   ├── astro.config.ts                   # Astro config with the intlayer() and react() integrations
   ├── intlayer.config.ts
   ├── package.json
   └── tsconfig.json
   

   Konfiguracja

   Utwórz plik konfiguracyjny, aby zdefiniować języki swojej aplikacji:

   intlayer.config.ts

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   import { Locales, type IntlayerConfig } from "intlayer";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         Locales.POLISH,
         // Twoje inne języki
       ],
       defaultLocale: Locales.ENGLISH,
     },
   };
   
   export default config;
   

   Za pośrednictwem tego pliku konfiguracyjnego możesz ustawić zlokalizowane adresy URL, przekierowania oprogramowania pośredniczącego, nazwy plików cookie, lokalizację i rozszerzenia deklaracji treści, wyłączyć dzienniki Intlayer w konsoli i wiele więcej. Pełną listę dostępnych parametrów znajdziesz w dokumentacji konfiguracji.

   dokumentacji konfiguracji
3. 3

   Zintegruj Intlayer ze swoją konfiguracją Astro

   Dodaj wtyczkę intlayer do konfiguracji Astro oraz integrację React.

   astro.config.ts

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   // @ts-check
   
   import { intlayer } from "astro-intlayer";
   import react from "@astrojs/react";
   import { defineConfig } from "astro/config";
   
   // https://astro.build/config
   export default defineConfig({
     integrations: [intlayer(), react()],
   });
   

   Wtyczka integracyjna intlayer() służy do integracji Intlayer z Astro. Zapewnia ona generowanie plików deklaracji treści i monitoruje je w trybie deweloperskim. Definiuje zmienne środowiskowe Intlayer w aplikacji Astro i udostępnia aliasy w celu optymalizacji wydajności.

   Integracja react() pozwala na używanie islandów komponentów React poprzez client:only="react".

4. 4

   Zadeklaruj swoją treść

   Twórz i zarządzaj swoimi deklaracjami treści, aby przechowywać tłumaczenia:

   src/app.content.tsx

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   import { t, type Dictionary } from "intlayer";
   import type { ReactNode } from "react";
   
   const appContent = {
     key: "app",
     content: {
       title: t({
         en: "Hello World",
         fr: "Bonjour le monde",
         es: "Hola mundo",
         pl: "Witaj świecie",
       }),
     },
   } satisfies Dictionary;
   
   export default appContent;
   

   Deklaracje treści mogą być definiowane w dowolnym miejscu aplikacji, pod warunkiem, że są zawarte w contentDir (domyślnie ./src) i pasują do rozszerzenia pliku deklaracji treści (domyślnie .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

   Więcej informacji znajdziesz w dokumentacji deklaracji treści.

   dokumentacji deklaracji treści
5. 5

   Korzystanie z treści w Astro

   Używaj słowników w plikach .astro za pomocą hooków wyeksportowanych przez astro-intlayer. Dzielą one sygnatury z react-intlayer: useIntlayer("key") zwraca zawartość słownika, a useLocale() bieżące ustawienia regionalne, bez konieczności przekazywania argumentów.

   Ustawienia regionalne pochodzą z middleware astro-intlayer, które integracja rejestruje przed Twoim własnym src/middleware.ts. Rozpoznaje je dla każdego żądania, na podstawie prefiksu URL, następnie ustawień regionalnych zapisanych przez klienta (cookie lub nagłówek), a potem Accept-Language, i zapisuje w Astro.locals.intlayer. Wstępnie renderowane strony używają tylko URL, ponieważ są renderowane raz dla każdego odwiedzającego.

   Powinieneś również dodać metadane SEO (takie jak linki hreflang i kanoniczne) na każdej stronie oraz wprowadzić island React dla interaktywnej treści po stronie klienta.

   src/pages/[...locale]/index.astro

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   ---
   import { useIntlayer, useLocale } from "astro-intlayer";
   import {
     getLocalizedUrl,
     getPrefix,
     localeMap,
     defaultLocale,
     getHTMLTextDir,
   } from "intlayer";
   import { ReactIsland } from "../../components/react/ReactIsland";
   
   export const getStaticPaths = () => {
     return localeMap(({ locale }) => ({
       params: { locale: getPrefix(locale).localePrefix },
     }));
   };
   
   // Ustawienia regionalne rozpoznane przez middleware (np. /pl/about -> 'pl')
   const { locale } = useLocale();
   
   // Zawartość słownika 'app' dla tych ustawień regionalnych
   const { title } = useIntlayer("app");
   ---
   
   <!doctype html>
   <html lang={locale} dir={getHTMLTextDir(locale)}>
     <head>
       <meta charset="utf-8" />
       <meta name="viewport" content="width=device-width" />
       <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
       <title>{title}</title>
   
       <!-- Link kanoniczny: Informuje wyszukiwarki o głównej wersji tej strony -->
       <link
         rel="canonical"
         href={new URL(getLocalizedUrl(Astro.url.pathname, locale), Astro.site)}
       />
   
       <!-- Hreflang: Informuje Google o wszystkich zlokalizowanych wersjach -->
       {
         localeMap(({ locale: mapLocale }) => (
           <link
             rel="alternate"
             hreflang={mapLocale}
             href={new URL(
               getLocalizedUrl(Astro.url.pathname, mapLocale),
               Astro.site
             )}
           />
         ))
       }
   
       <!-- x-default: Opcja rezerwowa, gdy język nie pasuje do języka użytkownika -->
       <link
         rel="alternate"
         hreflang="x-default"
         href={new URL(
           getLocalizedUrl(Astro.url.pathname, defaultLocale),
           Astro.site
         )}
       />
     </head>
     <body>
       <!-- Island React renderuje całą interaktywną treść, w tym przełącznik języków -->
       <ReactIsland locale={locale} client:only="react" />
     </body>
   </html>
   

   Jeśli chcesz użyć swojej treści w atrybucie string, takim jak alt, title, href, aria-label itp., możesz użyć wartości funkcji, np.:

   tsx

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   <img src={content.image.src.value} alt={content.image.value} />
   <img src={content.image.src.toString()} alt={content.image.toString()} />
   <img src={String(content.image.src)} alt={String(content.image)} />
   

   Astro.locals.intlayer udostępnia również locale, defaultLocale i availableLocales dla Twoich własnych middleware i endpointów. Przekaż ustawienia regionalne lub selektor jako drugi argument (useIntlayer("app", "fr"), useIntlayer("faq", { item: 2 })), aby nadpisać ustawienia regionalne żądania dla jednego wywołania.

   Uwaga na temat konfiguracji routingu: Używana przez Ciebie struktura katalogów zależy od ustawienia middleware.routing w intlayer.config.ts:

   • prefix-no-default (domyślnie): Zachowuje domyślny język w katalogu głównym (bez prefiksu) i dodaje prefiksy do pozostałych. Użyj [...locale], aby obsłużyć wszystkie przypadki.
   • prefix-all: Wszystkie adresy URL otrzymują prefiks języka. Możesz użyć standardowego [locale], jeśli nie musisz traktować katalogu głównego oddzielnie.
   • search-param o no-prefix: Katalogi językowe nie są wymagane. Język jest zarządzany za pomocą parametrów zapytania lub plików cookie.

6. 6

   Utworzenie komponentu React Island

   Utwórz komponent island, który opakowuje Twoją aplikację React i otrzymuje język wykryty przez serwer:

   src/components/react/ReactIsland.tsx

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   /** @jsxImportSource react */
   import { IntlayerProvider, useIntlayer } from "react-intlayer";
   import { type LocalesValues } from "intlayer";
   import { LocaleSwitcher } from "./LocaleSwitcher";
   
   function App() {
     const { title } = useIntlayer("app");
   
     return (
       <div>
         <h1>{title}</h1>
         <LocaleSwitcher />
       </div>
     );
   }
   
   export function ReactIsland({ locale }: { locale: LocalesValues }) {
     return (
       <IntlayerProvider locale={locale}>
         <App />
       </IntlayerProvider>
     );
   }
   

   Prop locale jest przekazywany ze strony Astro (wykrywanie po stronie serwera) do IntlayerProvider, służąc jako początkowy język dla wszystkich hooków React wewnątrz drzewa.

7. 7

   Dodanie przełącznika języków

   Utwórz komponent React LocaleSwitcher, który odczytuje dostępne języki i przechodzi do zlokalizowanego adresu URL, gdy użytkownik wybierze nowy język:

   src/components/react/LocaleSwitcher.tsx

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   /** @jsxImportSource react */
   import { useLocale } from "react-intlayer";
   import { getLocalizedUrl, getLocaleName, type LocalesValues } from "intlayer";
   
   export function LocaleSwitcher() {
     const { locale, availableLocales, setLocale } = useLocale({
       onLocaleChange: (newLocale: LocalesValues) => {
         // Przekieruj do zlokalizowanego adresu URL przy zmianie języka
         window.location.href = getLocalizedUrl(
           window.location.pathname,
           newLocale
         );
       },
     });
   
     return (
       <div className="locale-switcher">
         <span className="switcher-label">Zmień język:</span>
         <div className="locale-buttons">
           {availableLocales.map((localeItem) => (
             <button
               key={localeItem}
               onClick={() => setLocale(localeItem)}
               className={`locale-btn ${localeItem === locale ? "active" : ""}`}
               disabled={localeItem === locale}
             >
               <span className="ls-own-name">{getLocaleName(localeItem)}</span>
               <span className="ls-current-name">
                 {getLocaleName(localeItem, locale)}
               </span>
               <span class="ls-code">{localeItem.toUpperCase()}</span>
             </button>
           ))}
         </div>
       </div>
     );
   }
   

   Uwaga na temat trwałości: Użycie onLocaleChange do przekierowania przez window.location.href zapewnia, że nowy adres URL z prefiksem językowym zostanie odwiedzony. Pozwala to oprogramowaniu pośredniczącemu Intlayer ustawić plik cookie języka i zapamiętać preferencje użytkownika przy przyszłych wizytach.

   LocaleSwitcher musi być renderowany wewnątrz IntlayerProvider - użyj go w swoim komponencie island (jak pokazano w kroku 6).

8. 8

   Sitemap i Robots.txt

   Intlayer oferuje narzędzia do dynamicznego generowania zlokalizowanej mapy witryny oraz pliku robots.txt.

   Sitemap

   Intlayer comes with a built-in sitemap generator to help you create a sitemap for your application easily. It handles localized routes and adds the necessary metadata for search engines.

   The Intlayer generated sitemap supports the xhtml:link namespace (Hreflang XML Extensions). Unlike the default sitemap generators that only list raw URLs, Intlayer automatically creates the required bidirectional links between all language versions of a page (e.g., /about, /about?lang=fr, and /about?lang=es). This ensures search engines correctly index and serve the right language version to the right audience.

   Utwórz plik src/pages/sitemap.xml.ts, aby wygenerować mapę witryny obejmującą wszystkie Twoje zlokalizowane trasy.

   src/pages/sitemap.xml.ts

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   import type { APIRoute } from "astro";
   import { generateSitemap, type SitemapUrlEntry } from "intlayer";
   
   const pathList: SitemapUrlEntry[] = [
     { path: "/", changefreq: "daily", priority: 1.0 },
     { path: "/about", changefreq: "monthly", priority: 0.7 },
   ];
   
   export const GET: APIRoute = async ({ site }) => {
     const xmlOutput = generateSitemap(pathList, {
       siteUrl: "https://example.com",
     });
   
     return new Response(xmlOutput, {
       headers: { "Content-Type": "application/xml" },
     });
   };
   

   Robots.txt

   Utwórz plik src/pages/robots.txt.ts, aby kontrolować indeksowanie przez wyszukiwarki.

   src/pages/robots.txt.ts

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   import type { APIRoute } from "astro";
   import { getMultilingualUrls } from "intlayer";
   
   const getAllMultilingualUrls = (urls: string[]) =>
     urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);
   
   const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);
   
   export const GET: APIRoute = ({ site }) => {
     const robotsTxt = [
       "User-agent: *",
       "Allow: /",
       ...disallowedPaths.map((path) => `Disallow: ${path}`),
       "",
       `Sitemap: ${new URL("/sitemap.xml", site).href}`,
     ].join("\n");
   
     return new Response(robotsTxt, {
       headers: { "Content-Type": "text/plain" },
     });
   };
   

9. 17

   Wyodrębnij zawartość swoich komponentów

   Opcjonalne

   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ść.

   kompilator

   ekstraktor

   Aby go skonfigurować, możesz dodać sekcję compiler w pliku intlayer.config.ts:

   intlayer.config.ts

   Kopiuj zawartość

   Kopiuj kod

   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;
   

   Polecenie wyodrębnianiaKompilator Babel

   Uruchom ekstraktor, aby przetransformować komponenty i wyodrębnić zawartość

   bash

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   npx intlayer extract
   

   Zbuduj aplikację, aby przekształcić komponenty i wyodrębnić treść

   bash

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   npm run build # Lub npm run dev
   

Konfiguracja TypeScript

Intlayer wykorzystuje rozszerzenie modułów (module augmentation), aby skorzystać z TypeScript, czyniąc bazę kodu bardziej solidną.

Upewnij się, że Twoja konfiguracja TypeScript zawiera automatycznie generowane typy.

{
  // ... Twoja istniejąca konfiguracja TypeScript
  "include": [
    // ... Twoja istniejąca konfiguracja TypeScript
    ".intlayer/**/*.ts", // Uwzględnij automatycznie generowane typy
  ],
}

Konfiguracja Git

Zaleca się ignorowanie plików generowanych przez Intlayer. Zapobiega to ich przesyłaniu do repozytorium Git.

Aby to zrobić, dodaj następujące instrukcje do pliku .gitignore:

# Ignoruj pliki generowane przez Intlayer
.intlayer

Rozszerzenie VS Code

Aby poprawić wrażenia z programowania z Intlayer, możesz zainstalować oficjalne rozszerzenie Intlayer dla VS Code.

To rozszerzenie zapewnia:

• Autouzupełnianie kluczy tłumaczeń.
• Wykrywanie błędów w czasie rzeczywistym dla brakujących tłumaczeń.
• Podgląd inline przetłumaczonej treści.
• Szybkie akcje do łatwego tworzenia i aktualizowania tłumaczeń.

Więcej informacji na temat korzystania z rozszerzenia znajdziesz w dokumentacji rozszerzenia VS Code.

Pogłębiaj swoją wiedzę

Jeśli chcesz dowiedzieć się więcej, możesz również wdrożyć Edytor Wizualny lub użyć CMS, aby wyeksternalizować swoją treść.

Często Zadawane Pytania