Przetłumacz swoją stronę Vite i Solid za pomocą Intlayer | Internacjonalizacja (i18n)

Table of Contents

Ten pakiet jest w trakcie rozwoju. Zobacz zgłoszenie po więcej informacji. Pokaż swoje zainteresowanie Intlayer dla Solid, polubiając to zgłoszenie

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 dla TypeScript dzięki automatycznie generowanym typom, co poprawia autouzupełnianie i wykrywanie błędów.
• Skorzystaj z zaawansowanych funkcji, takich jak dynamiczne wykrywanie i przełączanie lokalizacji.

Przewodnik krok po kroku, jak skonfigurować Intlayer w aplikacji Vite i Solid

Spis treści

Krok 1: Instalacja zależności

Zainstaluj niezbędne pakiety za pomocą npm:

npm install intlayer solid-intlayernpm install vite-intlayer --save-devnpx intlayer init

• intlayer

  Podstawowy pakiet, który dostarcza narzędzia do internacjonalizacji do zarządzania konfiguracją, tłumaczeń, deklaracji treści, transpilecji oraz poleceń CLI.

• solid-intlayer Pakiet integrujący Intlayer z aplikacją Solid. Zapewnia dostawców kontekstu oraz hooki do internacjonalizacji w Solid.

• vite-intlayer Zawiera wtyczkę Vite do integracji Intlayer z bundlerem Vite, a także middleware do wykrywania preferowanej lokalizacji użytkownika, zarządzania ciasteczkami oraz obsługi przekierowań URL.

Krok 2: Konfiguracja projektu

Utwórz plik konfiguracyjny do konfiguracji języków Twojej aplikacji:

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // Twoje pozostałe locale
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

Poprzez ten plik konfiguracyjny 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: Zintegruj Intlayer w swojej konfiguracji Vite

Dodaj wtyczkę intlayer do swojej konfiguracji.

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react-swc";
import { intlayer } from "vite-intlayer";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react(), intlayer()],
});

Wtyczka Vite intlayer() służy do integracji Intlayer z Vite. Zapewnia budowanie plików deklaracji treści oraz monitoruje je w trybie deweloperskim. Definiuje zmienne środowiskowe Intlayer w aplikacji Vite. Dodatkowo dostarcza aliasy optymalizujące wydajność.

Krok 4: Zadeklaruj swoją treść

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

import { t, type Dictionary } from "intlayer";

const appContent = {
  key: "app",
  content: {},
} satisfies Dictionary;

export default appContent;

Twoje deklaracje zawartości mogą być zdefiniowane w dowolnym miejscu w aplikacji, pod warunkiem, że znajdują się w katalogu contentDir (domyślnie ./src). Muszą również odpowiadać rozszerzeniu pliku deklaracji zawartości (domyślnie .content.{json,ts,tsx,js,jsx,mjs,cjs}).

Aby uzyskać więcej szczegółów, zapoznaj się z dokumentacją deklaracji zawartości.

Krok 5: Wykorzystaj Intlayer w swoim kodzie

Uzyskaj dostęp do swoich słowników treści w całej aplikacji:

import { createSignal, type Component } from "solid-js";import solidLogo from "./assets/solid.svg";import viteLogo from "/vite.svg";import "./App.css";import { IntlayerProvider, useIntlayer } from "solid-intlayer";const AppContent: Component = () => {  const [count, setCount] = createSignal(0);  const content = useIntlayer("app");  return (    <>      <div>        <a href="https://vitejs.dev" target="_blank">          <img src={viteLogo} class="logo" alt={content.viteLogo.value} />        </a>        <a href="https://www.solidjs.com/" target="_blank">          <img            src={solidLogo}            class="logo solid"            alt={content.solidLogo.value}          />        </a>      </div>      <h1>{content.title}</h1>      <div class="card">        <button onClick={() => setCount((count) => count + 1)}>          {content.count({ count: count() })}        </button>        <p>{content.edit}</p>      </div>      <p class="read-the-docs">{content.readTheDocs}</p>    </>  );};const App: Component = () => (  <IntlayerProvider>    <AppContent />  </IntlayerProvider>);export default App;

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

Jeśli chcesz użyć swojej zawartości w atrybucie string, takim jak alt, title, href, aria-label itp., musisz wywołać wartość funkcji, jak:

html

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)}" />

(Opcjonalnie) Krok 6: Zmień język swojej zawartości

Aby zmienić język swojej zawartości, możesz użyć funkcji setLocale dostarczonej przez hook useLocale. Ta funkcja pozwala ustawić lokalizację aplikacji i odpowiednio zaktualizować zawartość.

import { type Component, For } from "solid-js";import { Locales } from "intlayer";import { useLocale } from "solid-intlayer";const LocaleSwitcher: Component = () => {  const { locale, setLocale, availableLocales } = useLocale();  return (    <select      value={locale()}      onChange={(e) => setLocale(e.currentTarget.value as Locales)}    >      <For each={availableLocales}>        {(loc) => (          <option value={loc} selected={loc === locale()}>            {loc}          </option>        )}      </For>    </select>  );};

(Opcjonalnie) Krok 7: Dodaj lokalizowane routingi do swojej aplikacji

Celem tego kroku jest utworzenie unikalnych tras dla każdego języka. Jest to przydatne dla SEO i przyjaznych dla SEO adresów URL. Przykład:

- https://example.com/about- https://example.com/es/about- https://example.com/fr/about

Aby dodać zlokalizowane routingi do swojej aplikacji, możesz użyć @solidjs/router.

Najpierw zainstaluj niezbędne zależności:

npm install @solidjs/router

Następnie owiń swoją aplikację w Router i zdefiniuj swoje trasy używając localeMap:

import { render } from "solid-js/web";import { Router } from "@solidjs/router";import App from "./App";const root = document.getElementById("root");render(  () => (    <Router>      <App />    </Router>  ),  root!);

import { type Component } from "solid-js";import { Route } from "@solidjs/router";import { localeMap } from "intlayer";import { IntlayerProvider } from "solid-intlayer";import Home from "./pages/Home";import About from "./pages/About";const App: Component = () => (  <IntlayerProvider>    {localeMap(({ locale, urlPrefix }) => (      <Route        path={urlPrefix || "/"}        component={(props: any) => (          <IntlayerProvider locale={locale}>{props.children}</IntlayerProvider>        )}      >        <Route path="/" component={Home} />        <Route path="/about" component={About} />      </Route>    ))}  </IntlayerProvider>);export default App;

(Opcjonalnie) Krok 8: Zmień URL przy zmianie lokalizacji

Aby zmienić URL przy zmianie lokalizacji, możesz użyć właściwości onLocaleChange dostarczonej przez hook useLocale. Możesz użyć hooków useNavigate i useLocation z @solidjs/router do aktualizacji ścieżki URL.

import { type Component, For } from "solid-js";import { useLocation, useNavigate } from "@solidjs/router";import { getLocalizedUrl } from "intlayer";import { useLocale } from "solid-intlayer";const LocaleSwitcher: Component = () => {  const location = useLocation();  const navigate = useNavigate();  const { locale, setLocale, availableLocales } = useLocale({    onLocaleChange: (loc) => {      const pathWithLocale = getLocalizedUrl(location.pathname, loc);      navigate(pathWithLocale);    },  });  return (    <select      value={locale()}      onChange={(e) => setLocale(e.currentTarget.value as any)}    >      <For each={availableLocales}>        {(loc) => (          <option value={loc} selected={loc === locale()}>            {loc}          </option>        )}      </For>    </select>  );};

(Opcjonalnie) Krok 9: Zmień atrybuty języka i kierunku HTML

Zaktualizuj atrybuty lang i dir tagu <html>, aby pasowały do bieżącej lokalizacji dla dostępności i SEO.

import { createEffect, type Component } from "solid-js";import { useLocale } from "solid-intlayer";import { getHTMLTextDir } from "intlayer";const AppContent: Component = () => {  const { locale } = useLocale();  createEffect(() => {    document.documentElement.lang = locale();    document.documentElement.dir = getHTMLTextDir(locale());  });  return (    // ... Zawartość Twojej aplikacji  );};

(Opcjonalnie) Krok 10: Tworzenie lokalizowanego komponentu Link

Utwórz niestandardowy komponent Link, który automatycznie dodaje prefiks wewnętrznych URL z bieżącym językiem.

import { type ParentComponent } from "solid-js";import { A, type AnchorProps } from "@solidjs/router";import { getLocalizedUrl } from "intlayer";import { useLocale } from "solid-intlayer";export const Link: ParentComponent<AnchorProps> = (props) => {  const { locale } = useLocale();  const isExternal = () => props.href.startsWith("http");  const localizedHref = () =>    isExternal() ? props.href : getLocalizedUrl(props.href, locale());  return <A {...props} href={localizedHref()} />;};

(Opcjonalnie) Krok 11: Renderuj Markdown

Intlayer obsługuje renderowanie treści Markdown bezpośrednio w aplikacji Solid przy użyciu własnego wewnętrznego parsera. Domyślnie Markdown jest traktowany jako zwykły tekst. Aby renderować go jako bogaty HTML, owiń swoją aplikację w MarkdownProvider.

import { render } from "solid-js/web";import { MarkdownProvider } from "solid-intlayer/markdown";import App from "./App";const root = document.getElementById("root");render(  () => (    <MarkdownProvider>      <App />    </MarkdownProvider>  ),  root!);

Następnie możesz użyć go w swoich komponentach:

import { useIntlayer } from "solid-intlayer";const MyComponent = () => {  const content = useIntlayer("my-content");  return (    <div>      {/* Renderuje się jako HTML przez MarkdownProvider */}      {content.markdownContent}    </div>  );};

Konfiguracja TypeScript

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

{  "compilerOptions": {    // ...  },  "include": ["src", ".intlayer/**/*.ts"],}

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 swojego pliku .gitignore:

#  Ignoruj pliki generowane przez Intlayer.intlayer

Rozszerzenie VS Code

Aby poprawić swoje doświadczenie w pracy z Intlayer, możesz zainstalować oficjalne rozszerzenie Intlayer dla VS Code.

Zainstaluj z Marketplace VS Code

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 aktualizowanie tłumaczeń.

Aby uzyskać więcej szczegółów na temat korzystania z rozszerzenia, zapoznaj się z dokumentacją rozszerzenia Intlayer dla VS Code.

(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:

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;

npx intlayer extract

import { defineConfig } from "vite";import { intlayer, intlayerCompiler } from "vite-intlayer";export default defineConfig({ plugins: [   intlayer(),   intlayerCompiler(), // Dodaje wtyczkę kompilatora ],});

npm run build # Lub npm run dev

(Opcjonalnie) Sitemap i robots.txt (generacja przy buildzie)

Intlayer udostępnia generateSitemap i getMultilingualUrls - narzędzia do formatowania wielojęzycznych plików sitemap.xml i robots.txt dla crawlerów i automatycznego zapisu do public/. Zwykle uruchamia się mały skrypt Node przed Vite (np. hooki npm predev / prebuild).

Sitemap

Generator sitemap uwzględnia locale i dodaje metadane dla crawlerów.

Sitemap obsługuje przestrzeń nazw xhtml:link (hreflang). Zamiast płaskiej listy URL Intlayer tworzy dwukierunkowe powiązania wszystkich wersji językowych strony (np. /about, /fr/about lub /about?lang=fr w zależności od routingu).

Robots.txt

Użyj getMultilingualUrls, by reguły Disallow obejmowały wszystkie zlokalizowane warianty ścieżek.

1. Plik generate-seo.mjs w katalogu głównym

import fs from "fs";import path from "path";import { fileURLToPath } from "url";import { generateSitemap, getMultilingualUrls } from "intlayer";const __dirname = path.dirname(fileURLToPath(import.meta.url));const SITE_URL = (process.env.SITE_URL || "http://localhost:5173").replace(  /\/$/,  "");const pathList = [  { path: "/", changefreq: "daily", priority: 1.0 },  { path: "/about", changefreq: "monthly", priority: 0.7 },];const sitemapXml = generateSitemap(pathList, { siteUrl: SITE_URL });fs.writeFileSync(path.join(__dirname, "public", "sitemap.xml"), sitemapXml);const getAllMultilingualUrls = (urls) =>  urls.flatMap((url) => Object.values(getMultilingualUrls(url)));const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);const robotsTxt = [  "User-agent: *",  "Allow: /",  ...disallowedPaths.map((path) => `Disallow: ${path}`),  "",  `Sitemap: ${SITE_URL}/sitemap.xml`,].join("\n");fs.writeFileSync(path.join(__dirname, "public", "robots.txt"), robotsTxt);console.log("SEO files generated successfully.");

Pakiet intlayer musi być zainstalowany. W produkcji ustaw SITE_URL w środowisku (np. w CI).

Preferuj generate-seo.mjs dla ESM w Node. Przy generate-seo.js ustaw "type": "module" w package.json lub włącz ESM inaczej.

2. Uruchom skrypt przed Vite

{  "scripts": {    "dev": "vite",    "prebuild": "node generate-seo.mjs",    "build": "vite build",    "preview": "vite preview"  }}

Dostosuj polecenia dla pnpm lub yarn. Możesz też wywołać skrypt z CI.

Idź dalej

Aby pójść dalej, możesz zaimplementować edytor wizualny lub wyeksportować swoją zawartość, korzystając z CMS.