Die Überwindung der Sprachbarriere für Anwender Ihrer Software ist ein wichtiges Thema.
Englisch ist nicht mehr die universelle Sprache des Internets.
Ab März 2020 waren nur 25,9 % der Internetnutzer englischsprachig.
Die Wahrscheinlichkeit ist hoch, dass Ihre Benutzer an Ihrer Website vorbeispringen, wenn sie nicht lokalisiert ist.
Ohne eine mehrsprachige Website könnten Sie daher einen grossen Teil potenzieller Benutzer verpassen.
Im JavaScript-Ökosystem gibt es viele Internationalisierungs-Frameworks. Hier finden Sie einige Details zu einigen JavaScript-Internationalisierungs-Frameworks.
In diesem Artikel verwenden wir das i18next-Framework, um eine React.js-App zu internationalisieren. Diese Schritt-für-Schritt-Anleitung ist für Sie, wenn Sie nach einer Möglichkeit suchen, eine internationalisierte React.js-App zu erstellen (mit oder ohne Create React App).
Wenn es um React-Lokalisierung geht, ist eines der beliebtesten Frameworks i18next mit seiner React-Erweiterung react-i18next, und das aus guten Gründen:
i18next wurde Ende 2011 erstellt. Es ist älter als die meisten Bibliotheken, die Sie heutzutage verwenden, einschliesslich Ihrer wichtigsten Frontend-Technologie (React, Angular, Vue, ...). ➡️ nachhaltig
Basierend darauf, wie lange i18next bereits Open Source verfügbar ist, gibt es keinen echten i18n-Fall, der nicht mit i18next gelöst werden könnte. ➡️ reif
i18next kann in jeder Umgebung mit Javascript (und einigen Nicht-Javascript - .net, elm, iOS, Android, Ruby, ...) verwendet werden, mit jedem UI-Framework, mit jedem i18n-Format, ... die Möglichkeiten sind endlos. ➡️ erweiterbar
Es gibt viele Funktionen und Möglichkeiten, die Sie mit i18next im Vergleich zu anderen regulären 18n-Frameworks erhalten. ➡️ reich
Hier finden Sie weitere Informationen darüber, warum i18next so besonders ist und wie es funktioniert.
Fangen wir an...
Voraussetzungen
Stellen Sie sicher, dass Sie Node.js und npm installiert haben. Es ist am besten, wenn Sie etwas Erfahrung mit einfachem HTML, JavaScript und einfachem React.js haben, bevor Sie zu react-i18next springen. Dieses React-Lokalisierungsbeispiel ist nicht als React-Anfänger-Tutorial gedacht.
Einstieg
Nehmen Sie Ihr eigenes React-Projekt oder erstellen Sie ein neues, z.B. mit create-react-app.
npx create-react-app my-app
Wir werden die App anpassen, um die Sprache gemäss den Vorlieben des Benutzers zu erkennen.
Und wir werden einen Sprachumschalter erstellen, um den Inhalt zwischen verschiedenen Sprachen zu ändern.
Lassen Sie uns einige i18next-Abhängigkeiten installieren:
i18n // detect user language // learn more: https://github.com/i18next/i18next-browser-languageDetector .use(LanguageDetector) // pass the i18n instance to react-i18next. .use(initReactI18next) // init i18next // for all options read: https://www.i18next.com/overview/configuration-options .init({ debug: true, fallbackLng: 'en', interpolation: { escapeValue: false, // not needed for react as it escapes by default }, resources: { en: { translation: { // here we will place our translations... } } } });
exportdefault i18n;
Lassen Sie uns diese Datei irgendwo in unsere index.js-Datei importieren:
import logo from'./logo.svg'; import'./App.css'; import { useTranslation, Trans } from'react-i18next';
functionApp() { const { t } = useTranslation();
return ( <divclassName="App"> <headerclassName="App-header"> <imgsrc={logo}className="App-logo"alt="logo" /> <p> <Transi18nKey="description.part1"> Edit <code>src/App.js</code> and save to reload. </Trans> </p> <a className="App-link" href="https://reactjs.org" target="_blank" rel="noopener noreferrer" > {t('description.part2')} </a> </header> </div> ); }
exportdefault App;
Etwas mehr Aufwand ist nötig, wenn man High-Order-Components (HOC) verwenden möchte. Eine weitere Option in dieser Situation ist die Verwendung von withTranslation HOC.
Die Texte sind jetzt Teil der Übersetzungsressourcen:
i18n // detect user language // learn more: https://github.com/i18next/i18next-browser-languageDetector .use(LanguageDetector) // pass the i18n instance to react-i18next. .use(initReactI18next) // init i18next // for all options read: https://www.i18next.com/overview/configuration-options .init({ debug: true, fallbackLng: 'en', interpolation: { escapeValue: false, // not needed for react as it escapes by default }, resources: { en: { translation: { description: { part1: 'Edit <1>src/App.js</1> and save to reload.', part2: 'Learn React' } } } } });
exportdefault i18n;
Sprachumschalter
Lassen Sie uns nun einen Sprachumschalter definieren:
i18n // detect user language // learn more: https://github.com/i18next/i18next-browser-languageDetector .use(LanguageDetector) // pass the i18n instance to react-i18next. .use(initReactI18next) // init i18next // for all options read: https://www.i18next.com/overview/configuration-options .init({ debug: true, fallbackLng: 'en', interpolation: { escapeValue: false, // not needed for react as it escapes by default }, resources: { en: { translation: { description: { part1: 'Edit <1>src/App.js</1> and save to reload.', part2: 'Learn React' } } }, de: { translation: { description: { part1: 'Ändere <1>src/App.js</1> und speichere um neu zu laden.', part2: 'Lerne React' } } } } });
exportdefault i18n;
🥳 Toll, Sie haben gerade Ihren ersten Sprachumschalter erstellt!
Dank i18next-browser-languageDetector versucht es jetzt, die Browsersprache zu erkennen und diese Sprache automatisch zu verwenden, wenn Sie die Übersetzungen dafür bereitgestellt haben. Die manuell ausgewählte Sprache im Sprachumschalter wird im localStorage beibehalten, beim nächsten Besuch der Seite wird diese Sprache als bevorzugte Sprache verwendet.
Wie erhalte ich die aktuelle Sprache?
Seit i18next v21 gibt es i18next.resolvedLanguage.
Es ist auf die aktuell aufgelöste Sprache eingestellt und kann als primär verwendete Sprache verwendet werden, beispielsweise in einem Sprachumschalter.
Wenn Ihre erkannte Sprache zum Beispiel en-US ist und Sie Übersetzungen nur für en bereitgestellt haben, wird stattdessen i18next.resolvedLanguageen zurückgeben.
i18next.language vs. i18next.languages vs. i18next.resolvedLanguage
/* language */ i18next.language; // Wird auf die aktuell erkannte oder eingestellte Sprache gesetzt.
/* languages */ i18next.languages; // Ist auf ein Array von Sprachcodes gesetzt, die verwendet werden, um den Übersetzungswert zu suchen. // Wenn die Sprache eingestellt ist, wird dieses Array mit den neuen Sprachcodes gefüllt. // Sofern nicht überschrieben, wird dieses Array mit weniger spezifischen Versionen dieses Codes für Fallback-Zwecke gefüllt, gefolgt von der Liste der Fallback-Sprachen
// mit Fallback-Sprachen initialisieren i18next.init({ fallbackLng: ["es", "fr", "en-US", "dev"] }); // ändere die Sprache i18next.changeLanguage("en-US-xx"); // neue Sprache und ihre allgemeineren Formen, gefolgt von Fallbacks i18next.languages; // ["en-US-xx", "en-US", "en", "es", "fr", "dev"] // Sprache erneut ändern i18next.changeLanguage("de-DE"); // vorherige Sprache wird nicht beibehalten i18next.languages; // ["de-DE", "de", "es", "fr", "en-US", "dev"]
/* resolvedLanguage */ i18next.resolvedLanguage; // Wird auf die aktuell aufgelöste Sprache gesetzt. // Es kann als primär verwendete Sprache verwendet werden, // zum Beispiel in einem Sprachumschalter.
Interpolation und Pluralisierung
i18next geht über die Bereitstellung der standardmässigen i18n-Funktionen hinaus.
Aber sicher ist es in der Lage, Plurale und Interpolation zu verarbeiten.
Zählen wir jedes Mal, wenn die Sprache geändert wird:
i18n // detect user language // learn more: https://github.com/i18next/i18next-browser-languageDetector .use(LanguageDetector) // pass the i18n instance to react-i18next. .use(initReactI18next) // init i18next // for all options read: https://www.i18next.com/overview/configuration-options .init({ debug: true, fallbackLng: 'en', interpolation: { escapeValue: false, // not needed for react as it escapes by default }, resources: { en: { translation: { description: { part1: 'Edit <1>src/App.js</1> and save to reload.', part2: 'Learn React' }, counter_one: 'Changed language just once', counter_other: 'Changed language already {{count}} times' } }, de: { translation: { description: { part1: 'Ändere <1>src/App.js</1> und speichere um neu zu laden.', part2: 'Lerne React' }, counter_one: 'Die Sprache wurde erst ein mal gewechselt', counter_other: 'Die Sprache wurde {{count}} mal gewechselt' } } } });
Sehen Sie diese Warnung in der Entwicklungskonsole (debug: true)?
i18next::pluralResolver: Your environment seems not to be Intl API compatible, use an Intl.PluralRules polyfill. Will fallback to the compatibilityJSON v3 format handling.
Mit v21 hat i18next das Suffix mit dem in der Intl API.
In Umgebungen, in denen die API Intl.PluralRules nicht verfügbar ist (wie bei älteren Android-Geräten), müssen Sie möglicherweise zu polyfill die Intl.PluralRules-API.
Falls es nicht verfügbar ist, wird auf die Pluralbehandlung von i18next JSON format v3 zurückgegriffen. Und wenn Ihr json bereits die neuen Suffixe verwendet, werden Ihre Pluralschlüssel wahrscheinlich nicht angezeigt.
tldr;
npm install intl-pluralrules
1
import'intl-pluralrules'
Formatierung
Sehen wir uns nun an, wie wir verschiedene Datumsformate mit Hilfe von i18next und Luxon verwenden können, um das Datum zu verarbeiten und Zeit.
npm install luxon
Wir möchten eine Fusszeile haben, die das aktuelle Datum anzeigt:
1 2 3 4 5 6 7 8 9 10 11 12
import'./Footer.css';
const Footer = ({ t }) => ( <divclassName="Footer"> <div>{t('footer.date', { date: new Date() })}</div> </div> );
exportdefault Footer;
// imported in our App.js and used like this // <Footer t={t} />
Importieren Sie Luxon und definieren Sie eine Formatfunktion, wie in der Dokumentation dokumentiert, und fügen Sie den neuen Übersetzungsschlüssel hinzu:
i18n // detect user language // learn more: https://github.com/i18next/i18next-browser-languageDetector .use(LanguageDetector) // pass the i18n instance to react-i18next. .use(initReactI18next) // init i18next // for all options read: https://www.i18next.com/overview/configuration-options .init({ debug: true, fallbackLng: 'en', interpolation: { escapeValue: false, // not needed for react as it escapes by default // format: (value, format, lng) => { // legacy usage // if (value instanceof Date) { // return DateTime.fromJSDate(value).setLocale(lng).toLocaleString(DateTime[format]) // } // return value; // } }, resources: { en: { translation: { description: { part1: 'Edit <1>src/App.js</1> and save to reload.', part2: 'Learn React' }, counter_one: 'Changed language just once', counter_other: 'Changed language already {{count}} times', footer: { date: 'Today is {{date, DATE_HUGE}}' } } }, de: { translation: { description: { part1: 'Ändere <1>src/App.js</1> und speichere um neu zu laden.', part2: 'Lerne React' }, counter_one: 'Die Sprache wurde erst ein mal gewechselt', counter_other: 'Die Sprache wurde {{count}} mal gewechselt', footer: { date: 'Heute ist {{date, DATE_HUGE}}' } } } } });
😎 Cool, jetzt haben wir eine sprachspezifische Datumsformatierung!
Englisch:
Deutsch:
Kontext
Was ist mit einer bestimmten Begrüssungsnachricht basierend auf der aktuellen Tageszeit? also morgens, abends usw.
Dies ist dank der Funktion context von i18next möglich.
Lassen Sie uns eine getGreetingTime-Funktion erstellen und das Ergebnis als Kontextinformationen für unsere Fusszeilenübersetzung verwenden:
i18n // i18next-http-backend // loads translations from your server // https://github.com/i18next/i18next-http-backend .use(Backend) // detect user language // learn more: https://github.com/i18next/i18next-browser-languageDetector .use(LanguageDetector) // pass the i18n instance to react-i18next. .use(initReactI18next) // init i18next // for all options read: https://www.i18next.com/overview/configuration-options .init({ debug: true, fallbackLng: 'en', interpolation: { escapeValue: false, // not needed for react as it escapes by default // format: (value, format, lng) => { // legacy usage // if (value instanceof Date) { // return DateTime.fromJSDate(value).setLocale(lng).toLocaleString(DateTime[format]) // } // return value; // } }, resources: { en: { translation: { description: { part1: 'Edit <1>src/App.js</1> and save to reload.', part2: 'Learn React' }, counter_one: 'Changed language just once', counter_other: 'Changed language already {{count}} times', footer: { date: 'Today is {{date, DATE_HUGE}}', date_morning: 'Good morning! Today is {{date, DATE_HUGE}} | Have a nice day!', date_afternoon: 'Good afternoon! It\'s {{date, DATE_HUGE}}', date_evening: 'Good evening! Today was the {{date, DATE_HUGE}}' } } }, de: { translation: { description: { part1: 'Ändere <1>src/App.js</1> und speichere um neu zu laden.', part2: 'Lerne React' }, counter_one: 'Die Sprache wurde erst ein mal gewechselt', counter_other: 'Die Sprache wurde {{count}} mal gewechselt', footer: { date: 'Heute ist {{date, DATE_HUGE}}', date_morning: 'Guten Morgen! Heute ist {{date, DATE_HUGE}} | Wünsche einen schönen Tag!', date_afternoon: 'Guten Tag! Es ist {{date, DATE_HUGE}}', date_evening: 'Guten Abend! Heute war {{date, DATE_HUGE}}' } } } } });
Die Übersetzungen in unserer Datei i18n.js zu haben, funktioniert, ist aber für Übersetzer nicht so geeignet, damit zu arbeiten.
Lassen Sie uns die Übersetzungen vom Code trennen und sie in dedizierte JSON-Dateien einfügen.
Jetzt werden die Übersetzungen asynchron geladen, stellen Sie also sicher, dass Sie Ihre App mit einer Suspense-Komponente umschliessen, um diesen Fehler zu verhindern: Uncaught Error: App suspended while rendering, but no fallback UI was specified.
1 2 3 4 5 6 7 8 9 10 11 12 13 14
import { Suspense } from'react';
functionApp() { // your app's code... }
// here app catches the suspense from page in case translations are not yet loaded exportdefaultfunctionWrappedApp() { return ( <Suspensefallback="...is loading"> <App /> </Suspense> ); }
Jetzt sieht Ihre App immer noch gleich aus, aber Ihre Übersetzungen sind getrennt.
Wenn Sie eine neue Sprache unterstützen möchten, erstellen Sie einfach einen neuen Ordner und eine neue JSON-Übersetzungsdatei.
Dies gibt Ihnen die Möglichkeit, die Übersetzungen an einige Übersetzer zu senden.
Oder wenn Sie mit einem Übersetzungsmanagementsystem arbeiten, können Sie einfach die Dateien mit einem CLI synchronisieren.
Einer der Vorteile von react-i18next basiert auf i18next, es unterstützt die Trennung von Übersetzungen in mehrere Dateien - die in i18next "Namespaces" genannt werden.
Um mehrere Namespaces/Übersetzungsdateien zu verwenden, müssen Sie dies beim Aufruf von useTranslation angeben:
Indem Sie die Übersetzungen an einige Übersetzer oder Übersetzungsagenturen senden, haben Sie mehr Kontrolle und einen direkten Kontakt mit ihnen. Das bedeutet aber auch mehr Arbeit für Sie.
Dies ist ein traditioneller Weg. Beachten Sie jedoch, dass das Versenden von Dateien immer einen Overhead verursacht.
Gibt es eine bessere Option?
Auf jeden Fall!
i18next hilft dabei, die Anwendung zu übersetzen, und das ist grossartig – aber es steckt noch mehr dahinter.
Wie integrieren Sie eventuelle Übersetzungsdienste/-agenturen?
Wie behalten Sie den Überblick über neue oder entfernte Inhalte?
Wie gehen Sie mit der richtigen Versionierung um?
Wie stellen Sie Übersetzungsänderungen bereit, ohne Ihre vollständige Anwendung bereitzustellen?
Nachdem Sie die zu lokalisierenden Übersetzungen importiert haben, löschen Sie den Ordner locales:
Passen Sie die Datei i18n.js an, um das i18next-locize-backend zu verwenden, und stellen Sie sicher, dass Sie die Projekt-ID und den API-Schlüssel aus Ihrem Locize-Projekt kopieren:
const locizeOptions = { projectId: '0bbc223a-9aba-4a90-ab93-ab9d7bf7f780', apiKey: 'aaad4141-54ba-4625-ae37-657538fe29e7', // YOU should not expose your apps API key to production!!! referenceLng: 'en', };
i18n // i18next-locize-backend // loads translations from your project, saves new keys to it (saveMissing: true) // https://github.com/locize/i18next-locize-backend .use(Backend) // detect user language // learn more: https://github.com/i18next/i18next-browser-languageDetector .use(LanguageDetector) // pass the i18n instance to react-i18next. .use(initReactI18next) // init i18next // for all options read: https://www.i18next.com/overview/configuration-options .init({ debug: true, fallbackLng: 'en', interpolation: { escapeValue: false, // not needed for react as it escapes by default // format: (value, format, lng) => { // legacy usage // if (value instanceof Date) { // return DateTime.fromJSDate(value).setLocale(lng).toLocaleString(DateTime[format]) // } // return value; // } }, backend: locizeOptions });
// here app catches the suspense from page in case translations are not yet loaded exportdefaultfunctionWrappedApp() { return ( <Suspensefallback="...is loading"> <App /> </Suspense> ); }
fehlende Übersetzungen speichern
Dank der Verwendung der saveMissing-Funktion werden während der Entwicklung der App neue Schlüssel automatisch zu locize hinzugefügt.
Übergeben Sie einfach saveMissing: true in den i18next-Optionen:
const locizeOptions = { projectId: '0bbc223a-9aba-4a90-ab93-ab9d7bf7f780', apiKey: 'aaad4141-54ba-4625-ae37-657538fe29e7', // YOU should not expose your apps API key to production!!! referenceLng: 'en', };
i18n // i18next-locize-backend // loads translations from your project, saves new keys to it (saveMissing: true) // https://github.com/locize/i18next-locize-backend .use(Backend) // detect user language // learn more: https://github.com/i18next/i18next-browser-languageDetector .use(LanguageDetector) // pass the i18n instance to react-i18next. .use(initReactI18next) // init i18next // for all options read: https://www.i18next.com/overview/configuration-options .init({ debug: true, fallbackLng: 'en', interpolation: { escapeValue: false, // not needed for react as it escapes by default // format: (value, format, lng) => { // legacy usage // if (value instanceof Date) { // return DateTime.fromJSDate(value).setLocale(lng).toLocaleString(DateTime[format]) // } // return value; // } }, backend: locizeOptions, saveMissing: true });
Zusätzlich mit Hilfe des Auto-MachineTranslation-Workflows und der Verwendung der saveMissing-Funktionalität werden während der Entwicklung der App nicht nur neue Schlüssel zur automatischen Lokalisierung hinzugefügt, sondern auch automatisch per maschineller Übersetzung in die Zielsprachen übersetzt.
Sehen Sie sich dieses Video an, um zu sehen, wie der Arbeitsablauf der automatischen maschinellen Übersetzung aussieht!
const locizeOptions = { projectId: '0bbc223a-9aba-4a90-ab93-ab9d7bf7f780', apiKey: 'aaad4141-54ba-4625-ae37-657538fe29e7', // YOU should not expose your apps API key to production!!! referenceLng: 'en', };
i18n // locize-lastused // sets a timestamp of last access on every translation segment on locize // -> safely remove the ones not being touched for weeks/months // https://github.com/locize/locize-lastused .use(LastUsed) // locize-editor // InContext Editor of locize .use(locizePlugin) // i18next-locize-backend // loads translations from your project, saves new keys to it (saveMissing: true) // https://github.com/locize/i18next-locize-backend .use(Backend) // detect user language // learn more: https://github.com/i18next/i18next-browser-languageDetector .use(LanguageDetector) // pass the i18n instance to react-i18next. .use(initReactI18next) // init i18next // for all options read: https://www.i18next.com/overview/configuration-options .init({ debug: true, fallbackLng: 'en', interpolation: { escapeValue: false, // not needed for react as it escapes by default // format: (value, format, lng) => { // legacy usage // if (value instanceof Date) { // return DateTime.fromJSDate(value).setLocale(lng).toLocaleString(DateTime[format]) // } // return value; // } }, backend: locizeOptions, locizeLastUsed: locizeOptions, saveMissing: true });
Erstellen Sie zuerst in locize eine dedizierte Version für die Produktion. Aktivieren Sie die automatische Veröffentlichung für diese Version nicht, sondern veröffentlichen Sie sie manuell oder über die API oder über die CLI.
Schliesslich aktivieren Sie auch Cache-Control max-age für diese Produktionsversion.
const locizeOptions = { projectId: process.env.REACT_APP_LOCIZE_PROJECTID, apiKey: process.env.REACT_APP_LOCIZE_APIKEY, // YOU should not expose your apps API key to production!!! referenceLng: process.env.REACT_APP_LOCIZE_REFLNG, version: process.env.REACT_APP_LOCIZE_VERSION };
if (!isProduction) { // locize-lastused // sets a timestamp of last access on every translation segment on locize // -> safely remove the ones not being touched for weeks/months // https://github.com/locize/locize-lastused i18n.use(LastUsed); }
i18n // locize-editor // InContext Editor of locize .use(locizePlugin) // i18next-locize-backend // loads translations from your project, saves new keys to it (saveMissing: true) // https://github.com/locize/i18next-locize-backend .use(Backend) // detect user language // learn more: https://github.com/i18next/i18next-browser-languageDetector .use(LanguageDetector) // pass the i18n instance to react-i18next. .use(initReactI18next) // init i18next // for all options read: https://www.i18next.com/overview/configuration-options .init({ debug: true, fallbackLng: 'en', interpolation: { escapeValue: false, // not needed for react as it escapes by default // format: (value, format, lng) => { // legacy usage // if (value instanceof Date) { // return DateTime.fromJSDate(value).setLocale(lng).toLocaleString(DateTime[format]) // } // return value; // } }, backend: locizeOptions, locizeLastUsed: locizeOptions, saveMissing: !isProduction // you should not use saveMissing in production });
Während der Entwicklung werden Sie nun weiterhin fehlende Schlüssel speichern und die lastused Funktionalität nutzen. => npm run start
Und in der Produktionsumgebung sind saveMissing und lastused deaktiviert, und auch der API-Schlüssel wird nicht verfügbar gemacht. => npm run build && npm run serve