Stellen Sie Ihre Frage und erhalten Sie einen Resümee des Dokuments, indem Sie diese Seite und den AI-Anbieter Ihrer Wahl referenzieren
Durch die Integration des Intlayer MCP-Servers in Ihren bevorzugten AI-Assistenten können Sie alle Dokumente direkt von ChatGPT, DeepSeek, Cursor, VSCode usw. abrufen.
Dokumentation des MCP-Servers ansehenDer Inhalt dieser Seite wurde mit einer KI übersetzt.
Den englischen Originaltext ansehenWenn Sie eine Idee haben, um diese Dokumentation zu verbessern, zögern Sie bitte nicht, durch das Einreichen eines Pull-Requests auf GitHub beizutragen.
GitHub-Link zur DokumentationMarkdown des Dokuments in die Zwischenablage kopieren
Erste Schritte mit der Internationalisierung (i18n) mit Intlayer und TanStack Start (React)
Was ist Intlayer?
Intlayer ist ein Open-Source-i18n-Toolkit für React-Apps. Es bietet Ihnen:
- Komponentenlokale Wörterbücher mit TypeScript-Sicherheit.
- Dynamische Metadaten & Routen (SEO-bereit).
- Laufzeit-Sprachumschaltung (und Hilfsmittel zum Erkennen/Speichern von Sprachen).
- Vite-Plugin für Build-Zeit-Transformationen + Entwicklererlebnis (DX).
Diese Anleitung zeigt, wie man Intlayer in ein TanStack Start-Projekt integriert (das unter der Haube Vite und TanStack Router für Routing/SSR verwendet).
Schritt 1: Abhängigkeiten installieren
Kopieren Sie den Code in die Zwischenablage
# npmnpm i intlayer react-intlayernpm i -D vite-intlayer# pnpmpnpm add intlayer react-intlayerpnpm add -D vite-intlayer# yarnyarn add intlayer react-intlayeryarn add -D vite-intlayer
- intlayer: Kern (Konfiguration, Wörterbücher, CLI/Transformationen).
- react-intlayer: <IntlayerProvider> + Hooks für React.
- vite-intlayer: Vite-Plugin, plus optionales Middleware für Spracherkennung/-weiterleitungen (funktioniert in Entwicklung & SSR/Vorschau; für Produktions-SSR in dependencies verschieben).
Schritt 2: Intlayer konfigurieren
Erstellen Sie intlayer.config.ts im Stammverzeichnis Ihres Projekts:
Kopieren Sie den Code in die Zwischenablage
import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = { internationalization: { locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH], defaultLocale: Locales.ENGLISH, }, // Sie können auch anpassen: contentDir, contentFileExtensions, Middleware-Optionen usw.};export default config;
CommonJS/ESM-Varianten sind identisch zu Ihrem Originaldokument, falls Sie cjs/mjs bevorzugen.
Vollständige Konfigurationsreferenz: siehe Intlayers Konfigurationsdokumentation.
Schritt 3: Fügen Sie das Vite-Plugin (und optional Middleware) hinzu
TanStack Start verwendet Vite, also fügen Sie Intlayers Plugin(s) zu Ihrer vite.config.ts hinzu:
Kopieren Sie den Code in die Zwischenablage
import { defineConfig } from "vite";import react from "@vitejs/plugin-react-swc";import { intlayerPlugin, intlayerMiddlewarePlugin } from "vite-intlayer";export default defineConfig({ plugins: [ react(), intlayerPlugin(), // Optional, aber empfohlen für die Erkennung der Sprache, Cookies & Weiterleitungen: intlayerMiddlewarePlugin(), ],});
Wenn Sie SSR bereitstellen, verschieben Sie vite-intlayer zu den dependencies, damit die Middleware in der Produktion ausgeführt wird.
Schritt 4: Deklarieren Sie Ihre Inhalte
Platzieren Sie Ihre Wörterbücher irgendwo unter ./src (Standard contentDir). Beispiel:
Kopieren Sie den Code in die Zwischenablage
import { t, type Dictionary } from "intlayer";import type { ReactNode } from "react";const appContent = { key: "app", content: { viteLogo: t({ de: "Vite-Logo", en: "Vite logo", fr: "Logo Vite", es: "Logo Vite", }), reactLogo: t({ de: "React-Logo", en: "React logo", fr: "Logo React", es: "Logo React", }), title: t({ de: "TanStack Start + React", en: "TanStack Start + React", fr: "TanStack Start + React", es: "TanStack Start + React", }), count: t({ de: "Zähler ist ", en: "count is ", fr: "le compte est ", es: "el recuento es ", }), edit: t<ReactNode>({ de: ( <> Bearbeite <code>src/routes/index.tsx</code> und speichere, um HMR zu testen </> ), en: ( <> Edit <code>src/routes/index.tsx</code> and save to test HMR </> ), fr: ( <> Éditez <code>src/routes/index.tsx</code> et enregistrez pour tester HMR </> ), es: ( <> Edita <code>src/routes/index.tsx</code> y guarda para probar HMR </> ), }), readTheDocs: t({ de: "Klicken Sie auf die Logos, um mehr zu erfahren", en: "Click the logos to learn more", fr: "Cliquez sur les logos pour en savoir plus", es: "Haz clic en los logotipos para saber más", }), },} satisfies Dictionary;export default appContent;
JSON/ESM/CJS-Varianten funktionieren genauso wie in Ihrem Originaldokument.
TSX-Inhalt? Vergessen Sie nicht import React from "react", falls Ihr Setup dies benötigt.
Schritt 5: TanStack Start mit Intlayer umschließen
Bei TanStack Start ist Ihre Root-Route der richtige Ort, um Provider zu setzen.
Kopieren Sie den Code in die Zwischenablage
import { Outlet, createRootRoute, Link as RouterLink,} from "@tanstack/react-router";import { IntlayerProvider, useIntlayer } from "react-intlayer";function AppShell() { // Beispiel für die Verwendung eines Wörterbuchs auf oberster Ebene: const content = useIntlayer("app"); return ( <div> <nav className="flex gap-3 p-3"> <RouterLink to="/">Startseite</RouterLink> <RouterLink to="/about">Über</RouterLink> </nav> <main className="p-6"> <h1>{content.title}</h1> <Outlet /> </main> </div> );}export const Route = createRootRoute({ component: () => ( <IntlayerProvider> <AppShell /> </IntlayerProvider> ),});
Dann verwenden Sie Ihre Inhalte in Seiten:
Kopieren Sie den Code in die Zwischenablage
import { createFileRoute } from "@tanstack/react-router";import { useIntlayer } from "react-intlayer";import reactLogo from "../assets/react.svg";export const Route = createFileRoute("/")({ component: () => { const content = useIntlayer("app"); return ( <> <button>{content.count}0</button> <p>{content.edit}</p> <img src={reactLogo} alt={content.reactLogo.value} width={48} height={48} /> <p className="opacity-70">{content.readTheDocs}</p> </> ); },});
String-Attribute (alt, title, aria-label, …) benötigen .value:
jsxCode kopierenKopieren Sie den Code in die Zwischenablage
<img alt={c.reactLogo.value} />
(Optional) Schritt 6: Sprachumschaltung (Client)
Kopieren Sie den Code in die Zwischenablage
import { Locales } from "intlayer";import { useLocale } from "react-intlayer";export function LocaleSwitcher() { const { setLocale } = useLocale(); return ( <div className="flex gap-2"> <button onClick={() => setLocale(Locales.ENGLISH)}>Englisch</button> <button onClick={() => setLocale(Locales.FRENCH)}>Französisch</button> <button onClick={() => setLocale(Locales.SPANISH)}>Spanisch</button> </div> );}
(Optional) Schritt 7: Lokalisierte Routenführung (SEO-freundliche URLs)
Sie haben zwei gute Muster mit TanStack Start. Wählen Sie eines aus.
Erstellen Sie einen dynamischen Segmentordner src/routes/$locale/, sodass Ihre URLs /:locale/... sind. Validieren Sie im $locale-Layout den params.locale, setzen Sie <IntlayerProvider locale=...> und rendern Sie ein <Outlet />. Dieser Ansatz ist unkompliziert, aber Sie werden den Rest Ihrer Routen unterhalb von $locale mounten, und Sie benötigen einen zusätzlichen nicht-präfixierten Baum, wenn Sie nicht möchten, dass die Standardsprache mit einem Präfix versehen wird.
(Optional) Schritt 8: URL beim Wechseln der Sprache aktualisieren
Mit Muster A (Basis-Pfad) bedeutet das Wechseln der Sprache, zu einem anderen Basis-Pfad zu navigieren:
Kopieren Sie den Code in die Zwischenablage
import { useRouter } from "@tanstack/react-router";import { Locales, getLocalizedUrl } from "intlayer";import { useLocale } from "react-intlayer";export function LocaleSwitcherNavigate() { const router = useRouter(); const { locale, setLocale } = useLocale(); const change = async (next: Locales) => { if (next === locale) return; const nextPath = getLocalizedUrl( window.location.pathname + window.location.search, next ); await router.navigate({ to: nextPath }); // bewahrt die Historie setLocale(next); }; return ( <div className="flex gap-2"> <button onClick={() => change(Locales.ENGLISH)}>English</button> <button onClick={() => change(Locales.FRENCH)}>Français</button> <button onClick={() => change(Locales.SPANISH)}>Español</button> </div> );}
(Optional) Schritt 9: <html lang> und dir (TanStack Start Dokument)
TanStack Start stellt ein Document (HTML-Wurzel-Shell) bereit, das Sie anpassen können. Setzen Sie lang und dir für Barrierefreiheit/SEO:
Kopieren Sie den Code in die Zwischenablage
import { Outlet, createRootRoute } from "@tanstack/react-router";import { IntlayerProvider } from "react-intlayer";import { getHTMLTextDir } from "intlayer";function Document({ locale, children,}: { locale: string; children: React.ReactNode;}) { return ( <html lang={locale} dir={getHTMLTextDir(locale)}> <head> <meta charSet="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> {/* ... */} </head> <body>{children}</body> </html> );}export const Route = createRootRoute({ component: () => ( <IntlayerProvider> {/* Wenn Sie die Locale auf dem Server berechnen, übergeben Sie sie an Document; andernfalls korrigiert der Client dies nach der Hydrierung */} <Document locale={document?.documentElement?.lang || "en"}> <Outlet /> </Document> </IntlayerProvider> ),});
Für eine clientseitige Korrektur können Sie auch Ihren kleinen Hook beibehalten:
Kopieren Sie den Code in die Zwischenablage
import { useEffect } from "react";import { useLocale } from "react-intlayer";import { getHTMLTextDir } from "intlayer";export const useI18nHTMLAttributes = () => { const { locale } = useLocale(); useEffect(() => { document.documentElement.lang = locale; document.documentElement.dir = getHTMLTextDir(locale); }, [locale]);};
(Optional) Schritt 10: Lokalisierte Link-Komponente
TanStack Router stellt ein <Link/> bereit, aber falls Sie jemals einen einfachen <a>-Tag benötigen, der interne URLs automatisch mit einem Präfix versieht:
Kopieren Sie den Code in die Zwischenablage
import { getLocalizedUrl } from "intlayer";import { forwardRef, type AnchorHTMLAttributes, type DetailedHTMLProps,} from "react";import { useLocale } from "react-intlayer";export interface LinkProps extends DetailedHTMLProps< AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement > {}const isExternal = (href?: string) => /^https?:\/\//.test(href ?? "");export const Link = forwardRef<HTMLAnchorElement, LinkProps>( ({ href, children, ...props }, ref) => { const { locale } = useLocale(); const hrefI18n = href && !isExternal(href) ? getLocalizedUrl(href, locale) : href; return ( <a href={hrefI18n} ref={ref} {...props}> {children} </a> ); });Link.displayName = "Link";
Wenn Sie Muster A (basepath) verwenden, löst TanStacks <Link to="/about" /> bereits über basepath zu /fr/about auf, daher ist ein benutzerdefinierter Link optional.
TypeScript
Fügen Sie die von Intlayer generierten Typen ein:
Kopieren Sie den Code in die Zwischenablage
{ "include": ["src", ".intlayer/**/*.ts"],}
Git
Ignorieren Sie die von Intlayer generierten Artefakte:
Kopieren Sie den Code in die Zwischenablage
.intlayer
VS Code Erweiterung
- Intlayer VS Code Erweiterung → Autovervollständigung, Fehler, Inline-Vorschauen, Schnellaktionen. Marketplace: intlayer.intlayer-vs-code-extension
Weiterführende Themen
- Visueller Editor
- CMS-Modus
- Lokalerkennung am Edge / Adapter
Dokumentationshistorie
Version | Datum | Änderungen |
---|---|---|
1.0.0 | 2025-08-11 | TanStack Start-Anpassung hinzugefügt |