Przetłumacz swoją witrynę Astro + Solid 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 + Solid

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 solid-js solid-intlayer @astrojs/solid-js
   

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

   • astro-intlayer Wtyczka integracyjna Astro służąca do połączenia Intlayer z bundlerem Vite; zawiera również oprogramowanie pośredniczące (middleware) do wykrywania preferowanego języka użytkownika, zarządzania plikami cookie i obsługi przekierowań URL.

   • solid-js Podstawowe pakiety Solid.

   • solid-intlayer Pakiet do integracji Intlayer z aplikacjami Solid. Zapewnia IntlayerProvider oraz prymitywy useIntlayer i useLocale dla międzynarodowości w Solid.

   • @astrojs/solid-js Oficjalna integracja Astro pozwalająca na używanie islandów komponentów Solid.

2. 2

   Skonfiguruj swój projekt

   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 oraz integrację Solid.

   astro.config.ts

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

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

   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 solid() pozwala na używanie islandów komponentów Solid poprzez client:only="solid-js".

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";
   
   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

   Możesz konsumować słowniki bezpośrednio w swoich plikach .astro, używając podstawowych pomocników wyeksportowanych z intlayer. Powinieneś również dodać metadane SEO (takie jak linki hreflang i kanoniczne) na każdej stronie oraz wprowadzić island Solid dla interaktywnej treści po stronie klienta.

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

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   ---
   import {
     getIntlayer,
     getLocaleFromPath,
     getLocalizedUrl,
     getHTMLTextDir,
     getPrefix,
     localeMap,
     defaultLocale,
     type LocalesValues,
   } from "intlayer";
   import { SolidIsland } from "../../components/solid/SolidIsland";
   
   export const getStaticPaths = () => {
     return localeMap(({ locale }) => ({
       params: { locale: getPrefix(locale).localePrefix },
     }));
   };
   
   const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;
   const { title } = getIntlayer("app", locale);
   ---
   
   <!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 Solid renderuje całą interaktywną treść, w tym przełącznik języków -->
       <SolidIsland locale={locale} client:only="solid-js" />
     </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)} />
   

   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 lub 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 Solid Island

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

   src/components/solid/SolidIsland.tsx

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   /** @jsxImportSource solid-js */
   import { IntlayerProvider, useIntlayer } from "solid-intlayer";
   import { type LocalesValues } from "intlayer";
   import { LocaleSwitcher } from "./LocaleSwitcher";
   
   function App() {
     const content = useIntlayer("app");
   
     return (
       <div>
         <h1>{content.title}</h1>
         <LocaleSwitcher />
       </div>
     );
   }
   
   export function SolidIsland({ 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 prymitywów Solid wewnątrz drzewa.

   W Solid useIntlayer zwraca funkcję dostępową (accessor) (np. `content.). Musisz ją wywołać, aby uzyskać dostęp do reaktywnej treści.

7. 7

   Dodanie przełącznika języków

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

   src/components/solid/LocaleSwitcher.tsx

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   /** @jsxImportSource solid-js */
   import { useLocale } from "solid-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 class="locale-switcher">
         <span class="switcher-label">Zmień język:</span>
         <div class="locale-buttons">
           {availableLocales.map((localeItem) => (
             <button
               onClick={() => setLocale(localeItem)}
               class={`locale-btn ${localeItem === locale() ? "active" : ""}`}
               disabled={localeItem === locale()}
             >
               <span class="ls-own-name">{getLocaleName(localeItem)}</span>
               <span class="ls-current-name">
                 {getLocaleName(localeItem, locale())}
               </span>
               <span class="ls-code">{localeItem.toUpperCase()}</span>
             </button>
           ))}
         </div>
       </div>
     );
   }
   

   Uwaga na temat reaktywności Solid: W Solid locale jest reaktywnym sygnałem dostępowym - zawsze wywołuj go jako locale(), aby pobrać bieżącą wartość.

   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 },
   ];
   
   const SITE_URL = import.meta.env.SITE ?? "http://localhost:4321";
   
   export const GET: APIRoute = async ({ site }) => {
     const xmlOutput = generateSitemap(pathList, { siteUrl: SITE_URL });
   
     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ść.

   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
   

   Since v9, the intlayerCompiler is included in the intlayer plugin. So you don't need to add it manually.

   Zaktualizuj vite.config.ts, aby dołączyć wtyczkę intlayerCompiler:

   vite.config.ts

   Kopiuj zawartość

   Kopiuj kod

   Skopiuj kod do schowka

   import { defineConfig } from "vite";
   import { intlayer, intlayerCompiler } from "vite-intlayer";
   
   export default defineConfig({
     plugins: [
       intlayer(),
       intlayerCompiler(), // Adds the compiler plugin
     ],
   });
   

   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