Przetłumacz swoją witrynę Astro za pomocą Intlayer | Międzynarodowość (i18n)

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

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
   

   • 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>.

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, a 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
   │   │   └── LocaleSwitcher.astro      # Locale switcher component
   │   └── pages
   │       ├── [...locale]
   │       │   └── index.astro           # Localized page (rest param also serves the default locale)
   │       ├── robots.txt.ts             # robots.txt endpoint
   │       └── sitemap.xml.ts            # Localized sitemap endpoint
   ├── astro.config.ts                   # Astro config with the intlayer() integration
   ├── 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.

3. 3

   Zintegruj Intlayer ze swoją konfiguracją Astro

   Dodaj wtyczkę intlayer do konfiguracji Astro.

   astro.config.ts

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

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

   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.

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.

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.

   Należy również dodać metadane SEO, takie jak hreflang i linki kanoniczne, do każdej strony oraz dołączyć przełącznik języków, aby umożliwić użytkownikom zmianę języka.

   src/pages/index.astro

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   ---
   import { useIntlayer, useLocale } from "astro-intlayer";
   import {
     getLocalizedUrl,
     defaultLocale,
     localeMap,
     getHTMLTextDir,
   } from "intlayer";
   import LocaleSwitcher from "../components/LocaleSwitcher.astro";
   
   // 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>
   
       <!-- Canonical link: Tells search engines which is the primary version of this page -->
       <link
         rel="canonical"
         href={new URL(getLocalizedUrl(Astro.url.pathname, locale), Astro.site)}
       />
   
       <!-- Hreflang: Tell Google about all localized versions -->
       {
         localeMap(({ locale: mapLocale }) => (
           <link
             rel="alternate"
             hreflang={mapLocale}
             href={new URL(
               getLocalizedUrl(Astro.url.pathname, mapLocale),
               Astro.site
             )}
           />
         ))
       }
   
       <!-- x-default: Fallback for users in unmatched languages -->
       <link
         rel="alternate"
         hreflang="x-default"
         href={new URL(
           getLocalizedUrl(Astro.url.pathname, defaultLocale),
           Astro.site
         )}
       />
     </head>
     <body>
       <header>
         <LocaleSwitcher />
       </header>
       <main>
         <h1>{title}</h1>
       </main>
     </body>
   </html>
   

   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.

6. 6

   Zlokalizowany routing

   Twórz dynamiczne segmenty tras (np. src/pages/[locale]/index.astro), aby serwować zlokalizowane strony:

   src/pages/[locale]/index.astro

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   ---
   import { getIntlayer } from "intlayer";
   
   const { title } = getIntlayer('app');
   ---
   
   <h1>{title}</h1>
   

   Uwaga dotycząca konfiguracji routingu: Struktura katalogów, którą używasz, zależy od ustawienia middleware.routing w pliku intlayer.config.ts:

   • prefix-no-default (domyślnie): Przechowuje domyślny język w katalogu głównym (bez prefiksu) i dodaje prefiksy do pozostałych. Użyj [...locale], aby uwzględnić wszystkie przypadki.
   • prefix-all: Wszystkie adresy URL mają prefiks języka. Możesz użyć standardowego [locale], jeśli nie musisz obsługiwać katalogu głównego osobno.
   • search-param lub no-prefix: Folder z językiem nie jest potrzebny. Język jest obsługiwany za pośrednictwem parametrów wyszukiwania lub ciasteczek.

7. 7

   Dodaj przełącznik języka

   Integracja z Astro dodaje oprogramowanie pośredniczące Vite, które pomaga w routingu uwzględniającym język i definiowaniu środowiska podczas programowania. Możesz również użyć własnej logiki lub narzędzi intlayer, takich jak getLocalizedUrl, aby tworzyć linki między językami.

   src/components/LocaleSwitcher.astro

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   ---
   import { useLocale } from "astro-intlayer";
   import { getLocaleName, getLocalizedUrl, getPathWithoutLocale } from "intlayer";
   
   const { locale, availableLocales } = useLocale();
   const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);
   ---
   
   <nav aria-label="Languages">
     <ul>
       {
         availableLocales.map((localeItem) => (
           <li key={localeItem} class="p-1">
             <a
               href={getLocalizedUrl(pathWithoutLocale, localeItem)}
               data-locale={localeItem}
               aria-current={localeItem === locale ? "page" : undefined}
             >
               {getLocaleName(localeItem)}
             </a>
           </li>
         ))
       }
     </ul>
   </nav>
   
   <script>
     // W przeglądarce ten sam import prowadzi do implementacji klienckiej
     import { useLocale } from "astro-intlayer";
     import { getLocalizedUrl, type LocalesValues } from "intlayer";
   
     // Zapisuje wybór w pliku cookie ustawień regionalnych, a następnie przechodzi do zlokalizowanego adresu URL
     const { setLocale } = useLocale({
       onLocaleChange: (newLocale) => {
         window.location.href = getLocalizedUrl(window.location.pathname, newLocale);
       },
     });
   
     const localeLinks = document.querySelectorAll("[data-locale]");
   
     localeLinks.forEach((link) => {
       link.addEventListener("click", (event) => {
         const locale = link.getAttribute("data-locale") as LocalesValues;
   
         event.preventDefault();
         setLocale(locale);
       });
     });
   </script>
   
   <style>
     nav {
       display: flex;
       gap: 1rem;
     }
     ul {
       display: flex;
       list-style: none;
       padding: 0;
       margin: 0;
       gap: 0.5rem;
     }
     a[aria-current="page"] {
       font-weight: bold;
       text-decoration: underline;
     }
   </style>
   

   Uwaga dotycząca trwałości: setLocale z klienckiego useLocale zapisuje preferencje językowe użytkownika w pliku cookie. Pozwala to Intlayer zapamiętać wybór i automatycznie przekierować użytkownika na preferowany język podczas kolejnych wizyt: strony renderowane na żądanie (adapter z output: 'server' lub prerender = false) są przekierowywane przez middleware Intlayer przed wysłaniem jakiegokolwiek kodu HTML, podczas gdy strony wstępnie wyrenderowane, serwowane jako pliki statyczne, są przekierowywane przez niewielki skrypt wstrzykiwany przez integrację na każdej stronie. Ustaw routing.enableProxy na false, aby wyłączyć oba mechanizmy. W środowisku astro dev plik cookie jest ignorowany jako źródło przekierowania, chyba że routing.enableProxy jest ustawione na true, dzięki czemu nieaktualny plik cookie nie przejmie stron, nad którymi pracujesz.

   Wzajemna kompatybilność serwer / klient: astro-intlayer prowadzi do swoich hooków serwerowych w nagłówku frontmatter (odczytując Astro.locals) oraz do hooków klienckich vanilla-intlayer w blokach <script> i wyspach (islands), z tymi samymi nazwami i strukturą zawartości. setLocale i onChange działają tylko na kliencie, wywołaj tam raz installIntlayer(), aby zainicjalizować magazyn klienta. astro-intlayer/client jawnie udostępnia punkt wejścia klienta.

8. 8

   Sitemap i Robots.txt

   Intlayer udostępnia narzędzia do dynamicznego generowania zlokalizowanych map witryny (sitemaps) i plików robots.txt.

   Mapa witryny

   Intlayer zawiera wbudowany generator mapy witryny, który ułatwia tworzenie mapy witryny dla aplikacji. Obsługuje zlokalizowane trasy i dodaje niezbędne metadane dla wyszukiwarek.

   Mapa witryny generowana przez Intlayer obsługuje przestrzeń nazw xhtml:link (Hreflang XML Extensions). W przeciwieństwie do domyślnych generatorów map witryny, które wymieniają tylko surowe adresy URL, Intlayer automatycznie tworzy wymagane dwukierunkowe linki między wszystkimi wersjami językowych strony (np. /about, /about?lang=fr i /about?lang=es). Zapewnia to, że wyszukiwarki prawidłowo indeksują i serwują odpowiednią wersję językową właściwej grupie odbiorców.

   Utwórz src/pages/sitemap.xml.ts, aby wygenerować mapę witryny zawierającą wszystkie 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 src/pages/robots.txt.ts aby kontrolować crawlowanie wyszukiwarek.

   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. 9

   Kontynuuj używanie swojej ulubionej frameworku

   Kontynuuj używanie swojej ulubionej frameworku do budowania aplikacji.

   • Intlayer + React: Intlayer with React
   • Intlayer + Vue: Intlayer with Vue
   • Intlayer + Svelte: Intlayer with Svelte
   • Intlayer + Solid: Intlayer with Solid
   • Intlayer + Preact: Intlayer with Preact
   • Intlayer + Lit: Intlayer with Lit
10. 15

    Wyodrębnij treść swoich komponentów

    Opcjonalne

    Jeśli posiadasz istniejącą bazę kodu, transformacja tysięcy plików może być czasochłonna.

    Aby ułatwić ten proces, Intlayer proponuje compiler / extractor do transformacji komponentów i wyodrębnienia treści.

    Aby to 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 konfiguracji
      compiler: {
        /**
         * Wskazuje, czy compiler powinien być włączony.
         */
        enabled: true,
    
        /**
         * Definiuje ścieżkę plików wyjściowych
         */
        output: ({ fileName, extension }) => `./${fileName}${extension}`,
    
        /**
         * Wskazuje, czy komponenty powinny być zapisane po transformacji.
         *
         * - Jeśli `true`, compiler przepisze plik komponentu na dysku. Transformacja będzie trwała, a compiler pominąć transformację w następnym procesie. W ten sposób compiler może transformować aplikację, a następnie można go usunąć.
         *
         * - Jeśli `false`, compiler wstrzyknie wywołanie funkcji `useIntlayer()` do kodu w outputzie budowania, i zachowa intaktną bazę kodu. Transformacja będzie wykonana tylko w pamięci.
         */
        saveComponents: false,
    
        /**
         * Prefiks klucza słownika
         */
        dictionaryKeyPrefix: "",
      },
    };
    
    export default config;
    

    Polecenie ExtractBabel compiler

    Uruchom extractor, aby transformować komponenty i wyodrębnić treść

    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.

Instalacja z VS Code Marketplace

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