Getting Started Internationalizing (i18n) with Intlayer and React Create App
Was ist Intlayer?
Intlayer ist eine innovative, Open-Source-Bibliothek für Internationalisierung (i18n), die entwickelt wurde, um die mehrsprachige Unterstützung in modernen Webanwendungen zu vereinfachen.
Mit Intlayer können Sie:
- Übersetzungen einfach verwalten mithilfe deklarativer Wörterbücher auf Komponentenebene.
- Metadaten, Routen und Inhalte dynamisch lokalisieren.
- TypScript-Unterstützung sicherstellen mit automatisch generierten Typen, die die Autovervollständigung und Fehlererkennung verbessern.
- Von fortschrittlichen Funktionen profitieren, wie dynamischer Lokalisierungserkennung und -wechsel.
Schritt-für-Schritt-Anleitung zur Einrichtung von Intlayer in einer React-Anwendung
Schritt 1: Abhängigkeiten installieren
Installieren Sie die benötigten Pakete mit npm:
1npm install intlayer react-intlayer1yarn add intlayer react-intlayer1pnpm add intlayer react-intlayerSchritt 2: Konfiguration Ihres Projekts
Erstellen Sie eine Konfigurationsdatei, um die Sprachen Ihrer Anwendung zu konfigurieren:
1// intlayer.config.ts
2
3import { Locales, type IntlayerConfig } from "intlayer";
4
5const config: IntlayerConfig = {
6 internationalization: {
7 locales: [
8 Locales.ENGLISH,
9 Locales.FRENCH,
10 Locales.SPANISH,
11 // Ihre weiteren Sprachen
12 ],
13 defaultLocale: Locales.ENGLISH,
14 },
15};
16
17export default config;Um alle verfügbaren Parameter zu sehen, siehe die Konfigurationsdokumentation hier.
Schritt 3: Intlayer in Ihre CRA-Konfiguration integrieren
Ändern Sie Ihre Skripte, um react-intlayer zu verwenden
1 "scripts": {
2 "build": "react-intlayer build",
3 "start": "react-intlayer start",
4 "transpile": "intlayer build"
5 },Hinweis: Die react-intlayer-Skripte basieren auf craco. Sie können auch Ihre eigene Einrichtung basierend auf dem Intlayer-craco-Plugin implementieren. Siehe Beispiel hier.
Schritt 4: Erklären Sie Ihren Inhalt
Erstellen und verwalten Sie Ihre Inhaltswörterbücher:
1// src/app.content.tsx
2import { t, type DeclarationContent } from "intlayer";
3import { type ReactNode } from "react";
4
5const appContent = {
6 key: "app",
7 content: {
8 getStarted: t<ReactNode>({
9 en: (
10 <>
11 Bearbeiten Sie <code>src/App.tsx</code> und speichern Sie, um neu zu
12 laden
13 </>
14 ),
15 fr: (
16 <>
17 Éditez <code>src/App.tsx</code> et enregistrez pour recharger
18 </>
19 ),
20 es: (
21 <>
22 Edita <code>src/App.tsx</code> y guarda para recargar
23 </>
24 ),
25 }),
26 reactLink: {
27 href: "https://reactjs.org",
28 content: t({
29 en: "Learn React",
30 fr: "Apprendre React",
31 es: "Aprender React",
32 }),
33 },
34 },
35} satisfies DeclarationContent;
36
37export default appContent;Siehe, wie Sie Ihre Intlayer-Deklarationsdateien deklarieren.
Schritt 5: Nutzen Sie Intlayer in Ihrem Code
Greifen Sie auf Ihre Inhaltswörterbücher in Ihrer Anwendung zu:
1import logo from "./logo.svg";
2import "./App.css";
3import { IntlayerProvider, useIntlayer } from "react-intlayer";
4import { LocaleSwitcher } from "./components/LangSwitcherDropDown";
5
6function AppContent() {
7 const content = useIntlayer("app");
8
9 return (
10 <header className="App-header">
11 <img src={logo} className="App-logo" alt="logo" />
12
13 {content.getStarted}
14 <a
15 className="App-link"
16 href={content.reactLink.href.value}
17 target="_blank"
18 rel="noopener noreferrer"
19 >
20 {content.reactLink.content}
21 </a>
22 </header>
23 );
24}
25
26function App() {
27 return (
28 <IntlayerProvider>
29 <div className="App">
30 {/* Um den useIntlayer-Hook ordnungsgemäß zu verwenden, sollten Sie auf Ihre Daten in einer Kinderkomponente zugreifen */}
31 <AppContent />
32 </div>
33 <div className="absolute bottom-5 right-5 z-50">
34 <LocaleSwitcher />
35 </div>
36 </IntlayerProvider>
37 );
38}
39
40export default App;Hinweis: Wenn Sie Ihren Inhalt in einem string-Attribut wie alt, title, href, aria-label usw. verwenden möchten, müssen Sie den Wert der Funktion aufrufen, wie:
tsx1<img src={content.image.src.value} alt={content.image.value} />
(Optional) Schritt 6: Ändern Sie die Sprache Ihres Inhalts
Um die Sprache Ihres Inhalts zu ändern, können Sie die setLocale-Funktion verwenden, die vom useLocale-Hook bereitgestellt wird. Diese Funktion ermöglicht es Ihnen, die Locale der Anwendung festzulegen und den Inhalt entsprechend zu aktualisieren.
1import { Locales } from "intlayer";
2import { useLocale } from "react-intlayer";
3
4const LocaleSwitcher = () => {
5 const { setLocale } = useLocale();
6
7 return (
8 <button onClick={() => setLocale(Locales.English)}>
9 Sprache auf Englisch ändern
10 </button>
11 );
12};(Optional) Schritt 7: Fügen Sie Ihrer Anwendung lokalisierte Routen hinzu
Ziel dieses Schrittes ist es, einzigartige Routen für jede Sprache zu erstellen. Dies ist nützlich für SEO und SEO-freundliche URLs. Beispiel:
1// /dashboard
2// /es/dashboard
3// /fr/dashboardStandardmäßig sind die Routen für die Standard-Sprache nicht vorangestellt. Wenn Sie die Standard-Sprache voranstellen möchten, können Sie die Option middleware.prefixDefault in Ihrer Konfiguration auf true setzen. Siehe die Konfigurationsdokumentation für mehr Informationen.
Um lokalisierte Routen zu Ihrer Anwendung hinzuzufügen, können Sie eine LocaleRouter-Komponente erstellen, die die Routen Ihrer Anwendung umschließt und die lokalisierte Routenverarbeitung übernimmt. Hier ist ein Beispiel mit React Router:
1// Notwendige Abhängigkeiten und Funktionen importieren
2import { Locales, getConfiguration, getPathWithoutLocale } from "intlayer"; // Hilfsfunktionen und -typen von 'intlayer'
3import { FC, PropsWithChildren } from "react"; // React-Typen für funktionale Komponenten und Props
4import { IntlayerProvider } from "react-intlayer"; // Provider für den Internationalisierungs-Kontext
5import {
6 BrowserRouter,
7 Routes,
8 Route,
9 useParams,
10 Navigate,
11 useLocation,
12} from "react-router-dom"; // Router-Komponenten zur Verwaltung der Navigation
13
14// Konfiguration von Intlayer destrukturieren
15const { internationalization, middleware } = getConfiguration();
16const { locales, defaultLocale } = internationalization;
17
18/**
19 * Eine Komponente, die die Lokalisierung verarbeitet und Kinder mit dem entsprechenden Locale-Kontext umschließt.
20 * Sie verwaltet die locale-basierte URL-Erkennung und -Validierung.
21 */
22const AppLocalized: FC<PropsWithChildren> = ({ children }) => {
23 const path = useLocation().pathname; // Den aktuellen URL-Pfad erhalten
24 const { locale } = useParams<{ locale: Locales }>(); // Das Locale-Parameter aus der URL extrahieren
25
26 // Bestimmen Sie das aktuelle Locale, falls nicht angegeben, auf das Standardlocale zurückfallen
27 const currentLocale = locale ?? defaultLocale;
28
29 // Entfernen Sie die Locale-Präfix vom Pfad, um einen Basis-Pfad zu erstellen
30 const pathWithoutLocale = removeLocaleFromUrl(
31 path // Aktueller URL-Pfad
32 );
33
34 /**
35 * Wenn middleware.prefixDefault true ist, sollte die Standard-Sprache immer vorangestellt werden.
36 */
37 if (middleware.prefixDefault) {
38 // Validieren Sie das Locale
39 if (!locale || !locales.includes(locale)) {
40 // Weiterleiten auf die Standard-Sprache mit dem aktualisierten Pfad
41 return (
42 <Navigate
43 to={`/${defaultLocale}/${pathWithoutLocale}`}
44 replace // Den aktuellen Verlaufseintrag mit dem neuen ersetzen
45 />
46 );
47 }
48
49 // Umschließen Sie die Kinder mit dem IntlayerProvider und setzen Sie die aktuelle Sprache
50 return (
51 <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>
52 );
53 } else {
54 /**
55 * Wenn middleware.prefixDefault false ist, ist die Standard-Sprache nicht vorangestellt.
56 * Stellen Sie sicher, dass die aktuelle Sprache gültig ist und nicht die Standard-Sprache ist.
57 */
58 if (
59 currentLocale.toString() !== defaultLocale.toString() &&
60 !locales
61 .filter(
62 (locale) => locale.toString() !== defaultLocale.toString() // Die Standard-Sprache ausschließen
63 )
64 .includes(currentLocale) // Überprüfen, ob die aktuelle Sprache in der Liste der gültigen Sprachen ist
65 ) {
66 // Weiterleiten zum Pfad ohne Locale-Präfix
67 return <Navigate to={pathWithoutLocale} replace />;
68 }
69
70 // Umschließen Sie die Kinder mit dem IntlayerProvider und setzen Sie die aktuelle Sprache
71 return (
72 <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>
73 );
74 }
75};
76
77/**
78 * Eine Router-Komponente, die locale-spezifische Routen einrichtet.
79 * Sie verwendet React Router zur Verwaltung der Navigation und zum Rendern lokalisierter Komponenten.
80 */
81export const LocaleRouter: FC<PropsWithChildren> = ({ children }) => (
82 <BrowserRouter>
83 <Routes>
84 <Route
85 // Routenmuster, um die Sprache (z.B. /en/, /fr/) zu erfassen und alle nachfolgenden Pfade zuzuordnen
86 path="/:locale/*"
87 element={<AppLocalized>{children}</AppLocalized>} // Umschließt Kinder mit Lokalisierungsverwaltung
88 />
89
90 {
91 // Wenn das Voranstellen der Standardsprache deaktiviert ist, die Kinder direkt am Stammpfad rendern
92 !middleware.prefixDefault && (
93 <Route
94 path="*"
95 element={<AppLocalized>{children}</AppLocalized>} // Umschließt Kinder mit Lokalisierungsverwaltung
96 />
97 )
98 }
99 </Routes>
100 </BrowserRouter>
101);(Optional) Schritt 8: Ändern Sie die URL, wenn das Locale wechselt
Um die URL zu ändern, wenn das Locale wechselt, können Sie das onLocaleChange-Prop verwenden, das vom useLocale-Hook bereitgestellt wird. Parallel dazu können Sie die Hooks useLocation und useNavigate von react-router-dom verwenden, um den URL-Pfad zu aktualisieren.
1import { Locales, getLocalizedUrl } from "intlayer";
2import { useLocale } from "react-intlayer";
3import { useLocation, useNavigate } from "react-router-dom";
4
5const LocaleSwitcher = () => {
6 const location = useLocation(); // Den aktuellen URL-Pfad erhalten. Beispiel: /fr/about
7 const navigate = useNavigate();
8
9 const changeUrl = (locale: Locales) => {
10 // Die URL mit dem aktualisierten Locale erstellen
11 // Beispiel: /es/about mit dem Locale auf Spanisch gesetzt
12 const pathWithLocale = getLocalizedUrl(location.pathname, locale);
13
14 // Den URL-Pfad aktualisieren
15 navigate(pathWithLocale);
16 };
17
18 const { setLocale } = useLocale({
19 onLocaleChange: changeUrl,
20 });
21
22 return (
23 <button onClick={() => setLocale(Locales.English)}>
24 Sprache auf Englisch ändern
25 </button>
26 );
27};TypeScript konfigurieren
Intlayer verwendet Modul-Augen zu den Vorteilen von TypeScript und macht Ihren Code stärker.
Stellen Sie sicher, dass Ihre TypeScript-Konfiguration die automatisch generierten Typen umfasst.
1// tsconfig.json
2
3{
4 // Ihre benutzerdefinierte Konfiguration
5 include: [
6 "src",
7 "types", // <- Die automatisch generierten Typen einbeziehen
8 ],
9}Git-Konfiguration
Es wird empfohlen, die von Intlayer generierten Dateien zu ignorieren. So vermeiden Sie, dass sie in Ihr Git-Repository eingeht.
Fügen Sie dazu die folgenden Anweisungen zu Ihrer .gitignore-Datei hinzu:
1# Ignorieren Sie die von Intlayer generierten Dateien
2.intlayerWenn 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 Dokumentation