Übersetzen Sie Ihre Vite and Solid mit Intlayer | Internationalisierung (i18n)

Inhaltsverzeichnis

Dieses Paket befindet sich in der Entwicklung. Weitere Informationen finden Sie im Issue. Zeigen Sie Ihr Interesse an Intlayer für Solid, indem Sie das Issue liken.

Warum Intlayer gegenüber Alternativen?

Im Vergleich zu Hauptlösungen wie „@solid-primitives/i18n“ oder „i18next“ ist Intlayer eine Lösung, die über integrierte Optimierungen verfügt wie:

Schritt-für-Schritt-Anleitung zur Einrichtung von Intlayer in einer Vite- und Solid-Anwendung

Inhaltsverzeichnis

1. 1

   Abhängigkeiten installieren

   Installieren Sie die notwendigen Pakete mit npm:

   bash

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

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

   • intlayer

     Das Kernpaket, das Internationalisierungswerkzeuge für Konfigurationsmanagement, Übersetzung, Inhaltsdeklaration, Transpilierung und CLI-Befehle bereitstellt.

   • solid-intlayer Das Paket, das Intlayer in Solid-Anwendungen integriert. Es stellt Kontextanbieter und Hooks für die Internationalisierung in Solid bereit.

   • vite-intlayer Enthält das Vite-Plugin zur Integration von Intlayer mit dem Vite-Bundler sowie Middleware zur Erkennung der bevorzugten Sprache des Benutzers, zur Verwaltung von Cookies und zur Handhabung von URL-Weiterleitungen.

2. 2

   Konfiguration Ihres Projekts

   Erstellen Sie eine Konfigurationsdatei, um die Sprachen Ihrer Anwendung zu konfigurieren:

   intlayer.config.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   import { Locales, type IntlayerConfig } from "intlayer";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         // Ihre weiteren Sprachversionen
       ],
       defaultLocale: Locales.ENGLISH,
     },
   };
   
   export default config;

   Über diese Konfigurationsdatei können Sie lokalisierte URLs, Middleware-Weiterleitungen, Cookie-Namen, den Speicherort und die Erweiterung Ihrer Inhaltsdeklarationen einstellen, Intlayer-Logs in der Konsole deaktivieren und vieles mehr. Für eine vollständige Liste der verfügbaren Parameter lesen Sie bitte die Konfigurationsdokumentation.

3. 3

   Integrieren Sie Intlayer in Ihre Vite-Konfiguration

   Fügen Sie das Intlayer-Plugin in Ihre Konfiguration ein.

   vite.config.ts

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   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()],
   });

   Das intlayer() Vite-Plugin wird verwendet, um Intlayer mit Vite zu integrieren. Es sorgt für den Aufbau von Inhaltsdeklarationsdateien und überwacht diese im Entwicklungsmodus. Es definiert Intlayer-Umgebungsvariablen innerhalb der Vite-Anwendung. Zusätzlich stellt es Aliase zur Optimierung der Leistung bereit.

4. 4

   Deklarieren Sie Ihren Inhalt

   Erstellen und verwalten Sie Ihre Inhaltsdeklarationen, um Übersetzungen zu speichern:

   src/app.content.tsx

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   import { t, type Dictionary } from "intlayer";
   
   const appContent = {
     key: "app",
     content: {},
   } satisfies Dictionary;
   
   export default appContent;

   Ihre Inhaltsdeklarationen können überall in Ihrer Anwendung definiert werden, sobald sie in das Verzeichnis contentDir aufgenommen werden (standardmäßig ./src). Und sie müssen die Dateiendung für Inhaltsdeklarationen erfüllen (standardmäßig .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

   Für weitere Details siehe die Dokumentation zur Inhaltsdeklaration.

5. 5

   Intlayer in Ihrem Code verwenden

   Greifen Sie auf Ihre Inhaltswörterbücher in Ihrer gesamten Anwendung zu:

   src/App.tsx

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   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;

   In Solid gibt useIntlayer eine Accessor-Funktion zurück (z. B. `content.). Sie müssen diese Funktion aufrufen, um auf den reaktiven Inhalt zuzugreifen.

   Wenn Sie Ihren Inhalt in einem string-Attribut verwenden möchten, wie alt, title, href, aria-label usw., müssen Sie den Wert der Funktion aufrufen, wie:

   html

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

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

6. 6

   Ändern Sie die Sprache Ihres Inhalts

   Optional

   Um die Sprache Ihres Inhalts zu ändern, können Sie die Funktion setLocale verwenden, die vom Hook useLocale bereitgestellt wird. Diese Funktion ermöglicht es Ihnen, die Locale der Anwendung festzulegen und den Inhalt entsprechend zu aktualisieren.

   src/components/LocaleSwitcher.tsx

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   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>  );};

7. 7

   Lokalisierte Navigation zu Ihrer Anwendung hinzufügen

   Optional

   Der Zweck dieses Schritts ist es, eindeutige Routen für jede Sprache zu erstellen. Dies ist nützlich für SEO und SEO-freundliche URLs. Beispiel:

   plaintext

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

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

   Um lokalisierte Navigation zu Ihrer Anwendung hinzuzufügen, können Sie @solidjs/router verwenden.

   Installieren Sie zuerst die notwendigen Abhängigkeiten:

   bash

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   npm install @solidjs/router

   Dann wickeln Sie Ihre Anwendung mit dem Router ein und definieren Sie Ihre Routen mit localeMap:

   src/index.tsx

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   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!);

   src/App.tsx

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   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;

8. 8

   URL ändern, wenn sich die Sprache ändert

   Optional

   Um die URL zu ändern, wenn sich die Locale ändert, können Sie die Prop onLocaleChange verwenden, die vom Hook useLocale bereitgestellt wird. Sie können die Hooks useNavigate und useLocation von @solidjs/router verwenden, um den URL-Pfad zu aktualisieren.

   src/components/LocaleSwitcher.tsx

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   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>  );};

9. 9

   HTML-Sprach- und Richtungsattribute wechseln

   Optional

   Aktualisieren Sie die Attribute lang und dir des <html>-Tags, damit sie mit der aktuellen Locale für Barrierefreiheit und SEO übereinstimmen.

   src/App.tsx

   Inhalt kopieren

   Code kopieren

   Kopieren Sie den Code in die Zwischenablage

   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 (    // ... Ihr Anwendungsinhalt  );};

10. 10

    Erstellen einer lokalisierten Link-Komponente

    Optional

    Erstellen Sie eine benutzerdefinierte Link-Komponente, die interne URLs automatisch mit der aktuellen Sprache präfixiert.

    src/components/Link.tsx

    Inhalt kopieren

    Code kopieren

    Kopieren Sie den Code in die Zwischenablage

    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()} />;};

11. 11

    Markdown rendern

    Optional

    Intlayer unterstützt das Rendern von Markdown-Inhalten direkt in Ihrer Solid-Anwendung mit seinem eigenen internen Parser. Standardmäßig wird Markdown als Klartext behandelt. Um es als Rich HTML zu rendern, wickeln Sie Ihre Anwendung mit dem MarkdownProvider ein.

    src/index.tsx

    Inhalt kopieren

    Code kopieren

    Kopieren Sie den Code in die Zwischenablage

    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!);

    Dann können Sie es in Ihren Komponenten verwenden:

    tsx

    Inhalt kopieren

    Code kopieren

    Kopieren Sie den Code in die Zwischenablage

    import { useIntlayer } from "solid-intlayer";const MyComponent = () => {  const content = useIntlayer("my-content");  return (    <div>      {/* Wird als HTML über MarkdownProvider gerendert */}      {content.markdownContent}    </div>  );};

12. 12

    Inhalt Ihrer Komponenten extrahieren

    Optional

    Wenn Sie eine bestehende Codebasis haben, kann die Transformation von Tausenden von Dateien zeitaufwendig sein.

    Um diesen Prozess zu erleichtern, bietet Intlayer einen Compiler / Extractor an, um Ihre Komponenten zu transformieren und den Inhalt zu extrahieren.

    Um es einzurichten, können Sie einen compiler-Abschnitt in Ihrer intlayer.config.ts-Datei hinzufügen:

    intlayer.config.ts

    Inhalt kopieren

    Code kopieren

    Kopieren Sie den Code in die Zwischenablage

    import { type IntlayerConfig } from "intlayer";
    
    const config: IntlayerConfig = {
      // ... Rest Ihrer Konfiguration
      compiler: {
        /**
         * Gibt an, ob der Compiler aktiviert sein soll.
         */
        enabled: true,
    
        /**
         * Definiert den Pfad der Ausgabedateien
         */
        output: ({ fileName, extension }) => `./${fileName}${extension}`,
    
        /**
         * Gibt an, ob die Komponenten nach der Transformation gespeichert werden sollen. Auf diese Weise kann der Compiler nur einmal ausgeführt werden, um die App zu transformieren, und dann entfernt werden.
         */
        saveComponents: false,
    
        /**
         * Präfix für Wörterbuchschlüssel
         */
        dictionaryKeyPrefix: "",
      },
    };
    
    export default config;

    ExtraktionsbefehlBabel-Compiler

    Führen Sie den Extractor aus, um Ihre Komponenten zu transformieren und den Inhalt zu extrahieren

    bash

    Inhalt kopieren

    Code kopieren

    Kopieren Sie den Code in die Zwischenablage

    npx intlayer extract

    Aktualisieren Sie Ihre vite.config.ts, um das intlayerCompiler-Plugin aufzunehmen:

    vite.config.ts

    Inhalt kopieren

    Code kopieren

    Kopieren Sie den Code in die Zwischenablage

    import { defineConfig } from "vite";import { intlayer, intlayerCompiler } from "vite-intlayer";export default defineConfig({ plugins: [   intlayer(),   intlayerCompiler(), // Fügt das Compiler-Plugin hinzu ],});

    bash

    Inhalt kopieren

    Code kopieren

    Kopieren Sie den Code in die Zwischenablage

    npm run build # Oder npm run dev

TypeScript konfigurieren

Stellen Sie sicher, dass Ihre TypeScript-Konfiguration die autogenerierten Typen enthält.

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

Git-Konfiguration

Es wird empfohlen, die von Intlayer generierten Dateien zu ignorieren. So vermeiden Sie, diese versehentlich in Ihr Git-Repository zu committen.

Dazu können Sie die folgenden Anweisungen in Ihre .gitignore-Datei aufnehmen:

#  Ignoriere die von Intlayer generierten Dateien.intlayer

VS Code Erweiterung

Um Ihre Entwicklungserfahrung mit Intlayer zu verbessern, können Sie die offizielle Intlayer VS Code Erweiterung installieren.

Installation aus dem VS Code Marketplace

Diese Erweiterung bietet:

• Autovervollständigung für Übersetzungsschlüssel.
• Echtzeit-Fehlererkennung für fehlende Übersetzungen.
• Inline-Vorschauen des übersetzten Inhalts.
• Schnellaktionen, um Übersetzungen einfach zu erstellen und zu aktualisieren.

Für weitere Details zur Nutzung der Erweiterung siehe die Intlayer VS Code Extension Dokumentation.

(Optional) Sitemap und robots.txt (Build-Zeit)

Intlayer stellt Hilfsfunktionen bereit - generateSitemap und getMultilingualUrls -, mit denen Sie mehrsprachige sitemap.xml- und robots.txt-Inhalte für Crawler formatieren und automatisch nach public/ schreiben können. Üblich ist ein kleines Node-Skript vor Vite (z. B. npm-predev-/prebuild-Hooks), damit die Dateien beim Build bzw. Dev-Server vorliegen.

Sitemap

Der Sitemap-Generator von Intlayer berücksichtigt Ihre Locales und die üblichen Metadaten für Crawler.

Die erzeugte Sitemap unterstützt den xhtml:link-Namensraum (Hreflang). Statt nur flacher URLs verknüpft Intlayer alle Sprachversionen einer Seite bidirektional (z. B. /about, /fr/about oder /about?lang=fr je nach Routing), was Suchmaschinen hilft.

Robots.txt

Mit getMultilingualUrls gelten Disallow-Regeln für alle lokalisierten Varianten sensibler Pfade.

1. generate-seo.mjs im Projektroot anlegen

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

intlayer muss installiert sein. Setzen Sie SITE_URL in der Produktion über die Umgebung (z. B. in der CI).

Nutzen Sie möglichst generate-seo.mjs für Node-ESM. Bei generate-seo.js "type": "module" in der package.json setzen oder Node mit ESM starten.

2. Skript vor Vite ausführen

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

Bei pnpm oder yarn die Befehle anpassen. Aufruf aus der CI ist ebenfalls möglich.

Weiterführende Schritte

Um weiterzugehen, können Sie den visuellen Editor implementieren oder Ihre Inhalte mit dem CMS auslagern.