Autor:
    Aymeric PINEAU
    Erstellung:2025-12-07Letzte Aktualisierung:2026-06-23

    Übersetzen Sie Ihre React Router v7 (File-System Routes) mit Intlayer | Internationalisierung (i18n)

    Diese Anleitung zeigt, wie Sie Intlayer für nahtlose Internationalisierung in React Router v7-Projekten mit dateisystembasiertem Routing (@react-router/fs-routes) mit lokalisierungsbewusstem Routing, TypeScript-Unterstützung und modernen Entwicklungsmethoden integrieren.

    Für clientseitiges Routing lesen Sie bitte die Anleitung Intlayer mit React Router v7.

    Inhaltsverzeichnis

    Warum Intlayer gegenüber Alternativen?

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

    Intlayer ist für die perfekte Zusammenarbeit mit React Router optimiert, indem es locale-aware Routing, Middleware zur Locale-Erkennung und alle Funktionen bietet, die für die Skalierung der Internationalisierung (i18n) erforderlich sind.

    Anstatt riesige JSON-Dateien in Ihre Seiten zu laden, laden Sie nur den erforderlichen Inhalt. Intlayer hilft Ihre Bundle- und Seitengröße um bis zu 50 % zu reduzieren.

    Durch die Festlegung des Inhaltsbereichs Ihrer Anwendung wird die Wartung für umfangreiche Anwendungen erleichtert. Sie können einen einzelnen Feature-Ordner duplizieren oder löschen, ohne die mentale Belastung durch die Überprüfung Ihrer gesamten Inhaltscodebasis auf sich nehmen zu müssen. Darüber hinaus ist Intlayer vollständig typisiert (fully typed), um die Genauigkeit Ihrer Inhalte sicherzustellen.

    Durch die gemeinsame Platzierung von Inhalten reduziert sich der von Large Language Models (LLMs) benötigte Kontext. Intlayer verfügt außerdem über eine Reihe von Tools, wie zum Beispiel eine CLI zum Testen auf fehlende Übersetzungen,LSP, MCP und agent skills, um die Entwicklererfahrung (DX) für KI-Agenten noch reibungsloser zu gestalten.

    Nutzen Sie die Automatisierung, um Ihre CI/CD-Pipeline mit dem LLM Ihrer Wahl auf Kosten Ihres KI-Anbieters zu übersetzen. Intlayer bietet außerdem einen Compiler zur Automatisierung der Inhaltsextraktion sowie eine Webplattform zur Unterstützung der Übersetzung im Hintergrund.

    Das Verbinden großer JSON-Dateien mit Komponenten kann zu Leistungs- und Reaktivitätsproblemen führen. Intlayer optimiert das Laden Ihrer Inhalte zur Erstellungszeit.

    Intlayer ist mehr als nur eine i18n-Lösung. Es bietet einen selbstgehosteten visuellen Editor und ein vollständiges CMS, um Ihnen zu helfen Verwalten Sie Ihre mehrsprachigen Inhalte in Echtzeit und gestalten Sie die Zusammenarbeit mit Übersetzern, Textern und anderen Teammitgliedern reibungslos. Inhalte können lokal und/oder remote gespeichert werden.

    Documentation References

    www.youtube.com

    This comprehensive guide provides everything you need to integrate Intlayer with React Router v7 using file-system based routing for a fully internationalized application with locale-aware routing and TypeScript support.

    Siehe Application Template auf GitHub.

    1. Middleware hinzufügen

      Installieren Sie die erforderlichen Pakete mit Ihrem bevorzugten Package Manager:

      bash
      npm install intlayer react-intlayer
npm install vite-intlayer --save-dev
npm install @react-router/fs-routes --save-dev
npx intlayer init
      • intlayer

      Das Core-Paket, das Internationalisierungstools für Konfigurationsmanagement, Übersetzung, Inhaltsdeklaration, Transpilation und CLI-Befehle bereitstellt.

      • react-intlayer Das Paket, das Intlayer mit React-Anwendungen integriert. Es bietet Context-Provider und Hooks für React-Internationalisierung.

      • vite-intlayer Includes the 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 Bearbeitung der URL-Umleitung.

      • @react-router/fs-routes Das Package, das dateiensystembasiertes Routing für React Router v7 ermöglicht.

    2. Konfiguration deines Projekts

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

      intlayer.config.ts
      import { type IntlayerConfig, Locales } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    defaultLocale: Locales.ENGLISH,
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
  },
};

export default config;

      Sie können auch das intlayerProxy verwenden, um serverseitiges Routing zu Ihrer Anwendung hinzuzufügen. Dieses Plugin erkennt automatisch die aktuelle Locale basierend auf der URL und setzt das entsprechende Locale-Cookie. Wenn keine Locale angegeben ist, bestimmt das Plugin die am besten geeignete Locale basierend auf den Spracheinstellungen des Browsers des Benutzers. Wenn keine Locale erkannt wird, erfolgt eine Weiterleitung zur Standard-Locale.

    3. Integrate Intlayer in Your Vite-Konfiguration

      Beachten Sie, dass Sie, um das intlayerProxy in der Produktion zu verwenden, das Paket vite-intlayer von devDependencies zu dependencies verschieben müssen.
      vite.config.ts
      import { reactRouter } from "@react-router/dev/vite";
import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

export default defineConfig({
  plugins: [
    reactRouter(),

    intlayer({
      proxy: {
        ignore: (req) => req.url?.startsWith("/api"),
      },
    }),
  ],
});
      Das intlayer() Vite-Plugin wird verwendet, um Intlayer mit Vite zu integrieren. Es sorgt für den Aufbau der Inhaltsdeklarationsdateien und überwacht diese im Entwicklungsmodus. Es definiert Intlayer-Umgebungsvariablen innerhalb der Vite-Anwendung. Zusätzlich stellt es Aliase bereit, um die Leistung zu optimieren.

    4. Konfigurieren der dateisystembasierten Routen von React Router v7

      Richten Sie Ihre Routing-Konfiguration ein, um dateisystembasierte Routen mit flatRoutes zu verwenden:

      app/routes.ts
      import type { RouteConfig } from "@react-router/dev/routes";
import { flatRoutes } from "@react-router/fs-routes";
import { configuration } from "intlayer";

const routes: RouteConfig = flatRoutes({
  // Inhaltsdeklarationsdateien ignorieren, damit sie nicht als Routen behandelt werden
  ignoredRouteFiles: configuration.content.fileExtensions.map(
    (fileExtension) => `**/*${fileExtension}`
  ),
});

export default routes;
      Die Funktion flatRoutes von @react-router/fs-routes aktiviert dateisystembasiertes Routing, bei dem die Dateistruktur im Verzeichnis routes/ die Routen Ihrer Anwendung bestimmt. Die Option ignoredRouteFiles stellt sicher, dass Intlayer-Inhaltsdeklarationsdateien (.content.ts, etc.) nicht als Routendateien behandelt werden.

    5. Routendateien mit Dateisystem-Konventionen erstellen

      Beim dateisystembasierten Routing verwenden Sie eine flache Namenskonvention, bei der Punkte (.) Pfadsegmente darstellen und Klammern () optionale Segmente bezeichnen.

      Erstellen Sie die folgenden Dateien in Ihrem Verzeichnis app/routes/:

      Dateistruktur

      bash
      app/
├── root.tsx                         # Layout-Wrapper für Locale-Routen
└──routes/
    ├── ($locale)._index.tsx         # Startseite (/, /es, etc.)
    ├── ($locale)._index.content.ts  # Startseiten-Inhalt
    ├── ($locale).about.tsx          # Über-Seite (/about, /es/about, etc.)
    └── ($locale).about.content.ts   # Über-Seiten-Inhalt

      Die Namenskonventionen:

      • ($locale) - Optionales dynamisches Segment für den Locale-Parameter
      • _layout - Layout-Route, die untergeordnete Routen umschließt
      • _index - Index-Route (wird am übergeordneten Pfad gerendert)
      • . (Punkt) - Trennt Pfadsegmente (z. B. ($locale).about → /:locale?/about)

      Layout-Komponente

      app/root.tsx
      import { getLocaleFromPath } from "intlayer";
import { IntlayerProvider } from "react-intlayer";
import {
  isRouteErrorResponse,
  Meta,
  Outlet,
  Scripts,
  ScrollRestoration,
  useLoaderData,
} from "react-router";

import type { Route } from "./+types/root";

import "./app.css";

// links and ErrorBoundary code

export async function loader({ request }: Route.LoaderArgs) {
  const locale = getLocaleFromPath(request.url);

  return { locale };
}

export function Layout({
  children,
}: { children: React.ReactNode } & Route.ComponentProps) {
  const data = useLoaderData<typeof loader>();
  const { locale } = data ?? {};

  return (
    <html lang={locale}>
      <head>
        <meta charSet="utf-8" />
        <meta content="width=device-width, initial-scale=1" name="viewport" />
        <Meta />
        <Links />
      </head>
      <body>
        <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
        <ScrollRestoration />
        <Scripts />
      </body>
    </html>
  );
}

      Index-Seite

      app/routes/($locale)._index.tsx
      import { getIntlayer, validatePrefix } from "intlayer";
import { useIntlayer } from "react-intlayer";
import { data } from "react-router";

import { LocaleSwitcher } from "~/components/locale-switcher";
import { Navbar } from "~/components/navbar";

import type { Route } from "./+types/($locale)._index";

export const loader = ({ params }: Route.LoaderArgs) => {
  const { locale } = params;

  const { isValid } = validatePrefix(locale);

  if (!isValid) {
    throw data("Locale not supported", { status: 404 });
  }
};

export const meta: Route.MetaFunction = ({ params }) => {
  const content = getIntlayer("page", params.locale);

  return [
    { title: content.title },
    { content: content.description, name: "description" },
  ];
};

export default function Page() {
  const { title, description, aboutLink } = useIntlayer("page");

  return (
    <div>
      <h1>{title}</h1>
      <p>{description}</p>
      <nav>
        <LocalizedLink to="/about">{aboutLink}</LocalizedLink>
      </nav>
    </div>
  );
}

      Über-Seite

      app/routes/($locale).about.tsx
      import { getIntlayer, validatePrefix } from "intlayer";
import { useIntlayer } from "react-intlayer";
import { data } from "react-router";

import { LocaleSwitcher } from "~/components/locale-switcher";
import { Navbar } from "~/components/navbar";

import type { Route } from "./+types/($locale).about";

export const loader = ({ params }: Route.LoaderArgs) => {
  const { locale } = params;

  const { isValid } = validatePrefix(locale);

  if (!isValid) {
    throw data("Locale not supported", { status: 404 });
  }
};

export const meta: Route.MetaFunction = ({ params }) => {
  const content = getIntlayer("about", params.locale);

  return [
    { title: content.title },
    { content: content.description, name: "description" },
  ];
};

export default function AboutPage() {
  const { title, content, homeLink } = useIntlayer("about");

  return (
    <div>
      <h1>{title}</h1>
      <p>{content}</p>
      <nav>
        <LocalizedLink to="/">{homeLink}</LocalizedLink>
      </nav>
    </div>
  );
}

    6. Deklarieren Sie Ihre Inhalte

      Erstellen und verwalten Sie Ihre Inhaltsdeklarationen, um Übersetzungen zu speichern. Platzieren Sie Inhaltsdateien neben Ihren Routendateien:

      app/routes/($locale)._index.content.ts
      import { t, type Dictionary } from "intlayer";

const pageContent = {
  key: "page",
  content: {
    title: t({
      en: "Welcome to React Router v7 + Intlayer",
      es: "Bienvenido a React Router v7 + Intlayer",
      fr: "Bienvenue sur React Router v7 + Intlayer",
    }),
    description: t({
      en: "Build multilingual applications with ease using React Router v7 and Intlayer.",
      es: "Cree aplicaciones multilingües fácilmente usando React Router v7 y Intlayer.",
      fr: "Créez des applications multilingues facilement avec React Router v7 et Intlayer.",
    }),
    aboutLink: t({
      en: "Learn About Us",
      es: "Aprender Sobre Nosotros",
      fr: "En savoir plus sur nous",
    }),
  },
} satisfies Dictionary;

export default pageContent;
      app/routes/($locale).about.content.ts
      import { t, type Dictionary } from "intlayer";

const aboutContent = {
  key: "about",
  content: {
    title: t({
      en: "About Us",
      es: "Sobre Nosotros",
      fr: "À propos de nous",
    }),
    content: t({
      en: "This is the about page content.",
      es: "Este es el contenido de la página de información.",
      fr: "Ceci est le contenu de la page à propos.",
    }),
    homeLink: t({
      en: "Home",
      es: "Inicio",
      fr: "Accueil",
    }),
  },
} satisfies Dictionary;

export default aboutContent;
      Ihre Inhaltsdeklarationen können überall in Ihrer Anwendung definiert werden, sobald sie in das Verzeichnis contentDir aufgenommen werden (standardmäßig ./app). Und sie müssen der Dateierweiterung für Inhaltsdeklarationen entsprechen (standardmäßig .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).
      Für weitere Details siehe die Dokumentation zur Inhaltsdeklaration.
      Wenn Ihre App bereits existiert, können Sie den Intlayer Compiler sowie den Extraktionsbefehl verwenden, um Tausende von Komponenten in einer Sekunde zu transformieren.

    7. Erstellen Sie locale-bewusste Komponenten

      Erstellen Sie eine LocalizedLink-Komponente für locale-bewusste Navigation:

      app/components/localized-link.tsx
      import type { FC } from "react";

import { getLocalizedUrl, type LocalesValues } from "intlayer";
import { useLocale } from "react-intlayer";
import { Link, type LinkProps, type To } from "react-router";

const isExternalLink = (to: string) => /^(https?:)?\/\//.test(to);

// Prüft, ob der Link extern ist
export const locacalizeTo = (to: To, locale: LocalesValues): To => {
  if (typeof to === "string") {
    if (isExternalLink(to)) {
      return to;
    }

    return getLocalizedUrl(to, locale);
  }

  if (isExternalLink(to.pathname ?? "")) {
    return to;
  }

  return {
    ...to,
    pathname: getLocalizedUrl(to.pathname ?? "", locale),
  };
};

// Lokalisierter Link-Komponenten für die Navigation
export const LocalizedLink: FC<LinkProps> = (props) => {
  const { locale } = useLocale();

  return <Link {...props} to={locacalizeTo(props.to, locale)} />;
};

      Falls Sie zu den lokalisierten Routen navigieren möchten, können Sie den useLocalizedNavigate Hook verwenden:

      app/hooks/useLocalizedNavigate.ts
      import { useLocale } from "react-intlayer";
import { type NavigateOptions, type To, useNavigate } from "react-router";

import { locacalizeTo } from "~/components/localized-link";

export const useLocalizedNavigate = () => {
  const navigate = useNavigate();
  const { locale } = useLocale();

  const localizedNavigate = (to: To, options?: NavigateOptions) => {
    const localedTo = locacalizeTo(to, locale);

    navigate(localedTo, options);
  };

  return localizedNavigate;
};

    8. Erstellen Sie eine Sprachumschalter-Komponente

      Erstellen Sie eine Komponente, die es Benutzern ermöglicht, die Sprache zu wechseln:

      app/components/locale-switcher.tsx
      import type { FC } from "react";

import {
  getHTMLTextDir,
  getLocaleName,
  getLocalizedUrl,
  getPathWithoutLocale,
  Locales,
} from "intlayer";
import { useIntlayer, useLocale } from "react-intlayer";
import { Link, useLocation } from "react-router";

export const LocaleSwitcher: FC = () => {
  const { localeSwitcherLabel } = useIntlayer("locale-switcher");
  const { pathname } = useLocation();

  const { availableLocales, locale } = useLocale();

  const pathWithoutLocale = getPathWithoutLocale(pathname);

  return (
    <ol>
      {availableLocales.map((localeItem) => (
        <li key={localeItem}>
          <Link
            aria-current={localeItem === locale ? "page" : undefined}
            aria-label={`${localeSwitcherLabel.value} ${getLocaleName(localeItem)}`}
            reloadDocument // Seite neu laden, um die neue Locale anzuwenden
            to={getLocalizedUrl(pathWithoutLocale, localeItem)}
          >
            <span>
              {/* Gebietsschema - z.B. FR */}
              {localeItem}
            </span>
            <span>
              {/* Sprache im eigenen Gebietsschema - z.B. Français */}
              {getLocaleName(localeItem, locale)}
            </span>
            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
              {/* Sprache im aktuellen Gebietsschema - z.B. Francés mit aktuellem Gebietsschema auf Locales.SPANISH gesetzt */}
              {getLocaleName(localeItem)}
            </span>
            <span dir="ltr" lang={Locales.ENGLISH}>
              {/* Sprache auf Englisch - z.B. Französisch */}
              {getLocaleName(localeItem, Locales.ENGLISH)}
            </span>
          </Link>
        </li>
      ))}
    </ol>
  );
};
      Um mehr über den useLocale Hook zu erfahren, siehe die Dokumentation.

    9. HTML-Attribute-Verwaltung hinzufügen

      Erstellen Sie einen Hook, um die HTML-Attribute lang und dir zu verwalten:

      app/hooks/useI18nHTMLAttributes.tsx
      import { getHTMLTextDir } from "intlayer";
import { useEffect } from "react";
import { useLocale } from "react-intlayer";

export const useI18nHTMLAttributes = () => {
  const { locale } = useLocale();

  useEffect(() => {
    document.documentElement.lang = locale;
    document.documentElement.dir = getHTMLTextDir(locale);
  }, [locale]);
};

      Dieser Hook wird bereits in der Layout-Komponente (root.tsx) verwendet, die in Schritt 5 gezeigt wird.

    10. Middleware hinzufügen

      Sie können auch intlayerProxy verwenden, um Server-seitiges Routing zu Ihrer Anwendung hinzuzufügen. Dieses Plugin erkennt automatisch das aktuelle Locale basierend auf der URL und setzt das entsprechende Locale-Cookie. Wenn kein Locale angegeben ist, bestimmt das Plugin das am besten geeignete Locale basierend auf den Spracheinstellungen des Browsers des Benutzers. Wenn kein Locale erkannt wird, wird es zum Standard-Locale weitergeleitet.

      Beachten Sie, dass Sie das vite-intlayer-Paket von devDependencies zu dependencies verschieben müssen, um den intlayerProxy in der Produktion zu verwenden.
      Seit Intlayer v9 ist intlayerProxy() direkt in das intlayer() Plugin integriert und wird standardmäßig über die routing.enableProxy Option (true als Standard) aktiviert. Eine separate Registrierung wie unten gezeigt ist nun optional — sie wird für Rückwärtskompatibilität und Setups beibehalten, die die Plugin-Reihenfolge kontrollieren müssen. Setzen Sie routing.enableProxy: false, um sich abzumelden. Siehe die v9-Versionshinweise.
      vite.config.ts
      import { reactRouter } from "@react-router/dev/vite";
import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

export default defineConfig({
  plugins: [
    reactRouter(),

    intlayer({
      proxy: {
        ignore: (req) => req.url?.startsWith("/api"),
      },
    }),
  ],
});

    11. 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
      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;

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

      bash
      npx intlayer extract
      Since v9, the intlayerCompiler is included in the intlayer plugin. So you don't need to add it manually.
      babel.config.js
      const {
  intlayerExtractBabelPlugin,
  getExtractPluginOptions,
} = require("@intlayer/babel");

module.exports = {
  presets: ["next/babel"],
  plugins: [
    // Inhalt aus Komponenten in Wörterbücher extrahieren
    [intlayerExtractBabelPlugin, getExtractPluginOptions()],
  ],
};
      bash
      npm run build # Oder npm run dev

    TypeScript konfigurieren

    Intlayer verwendet Module Augmentation, um die Vorteile von TypeScript zu nutzen und Ihren Code stabiler zu machen.

    Stellen Sie sicher, dass Ihre TypeScript-Konfiguration die automatisch generierten Typen enthält:

    tsconfig.json
    {
  // ... Ihre bestehenden Konfigurationen
  include: [
    // ... Ihre bestehenden Includes
    ".intlayer/**/*.ts", // Einschluss der automatisch generierten Typen
  ],
}

    Git-Konfiguration

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

    Fügen Sie dazu folgende Anweisungen in Ihre .gitignore-Datei ein:

    .gitignore
    # 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 lesen Sie die Intlayer VS Code Erweiterungsdokumentation.

    Weiterführende Schritte

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

    Dokumentationsverweise

    Dieser umfassende Leitfaden bietet alles, was Sie benötigen, um Intlayer mit React Router v7 für eine vollständig internationalisierte Anwendung mit lokalisierungsbewusstem Routing und TypeScript-Unterstützung zu integrieren.

    React Router v7Compiler