Internationalisierung in BigCommerce Catalyst: Ein umfassender Leitfaden für Entwickler

BigCommerce, Catalyst, Ecommerce

Unter „Lokalisierung und Internationalisierung“ in BigCommerce Catalyst versteht man die Möglichkeit, Käufern in verschiedenen Regionen ein personalisiertes Einkaufserlebnis zu bieten. Catalyst nutzt die Next.js App Router Internationalization-Bibliothek, um die bevorzugte Region eines Käufers zu erkennen und zu verfolgen. Dadurch wird die Bereitstellung von Inhalten in der richtigen Sprache, die Anwendung regionsspezifischer Formatierungen sowie die Anpassung des Produktangebots an bestimmte Regionen ermöglicht.

Hier werden wir die Internationalisierung aus der Perspektive eines einzelnen Catalyst-Kanals betrachten, der mehrere Sprachversionen unterstützt. Anschließend werden wir jedoch auch auf eine mögliche Multi-Storefront-Konfiguration eingehen.

Verfügbare Sprachversionen für die Internationalisierung in BigCommerce Catalyst

Denken Sie daran, dass die für Ihren Catalyst-Shop verfügbaren Sprachen bei der Ersteinrichtung des Shop-Kanals ausgewählt werden. Sie können die Standard- und verfügbaren Sprachen außerdem jederzeit auf der Registerkarte „Lokalisierung“ ändern, wenn Sie den Kanal im Kontrollpanel anzeigen.

Jede verfügbare Sprache wird durch einen Locale-Code (z. B. „en“) angegeben. Die für den Catalyst-Storefront verfügbaren Locales werden bei jedem neuen Build oder beim Start des Entwicklungsservers abgerufen und in der Konfiguration zur Build-Zeit gespeichert. Beachten Sie die folgenden wichtigen Speicherorte im Catalyst-Projekt:

  • next.config.ts: Die hier definierte SettingsQuery wird während des Builds ausgeführt, um die verfügbaren Sprachen abzurufen.
  • build-config: Hier befinden sich Dateien zur Verwaltung der Locale-Konfiguration während des Builds.
  • build-config/build-config.json: Diese Datei sollte in Ihrem Projekt vorhanden sein, wenn der Entwicklungsserver ausgeführt wurde. Sie enthält die generierte Locale-Konfiguration.

So wird die Spracheinstellung ermittelt

Catalyst ermittelt die Spracheinstellung standardmäßig anhand der Browsereinstellungen des Kunden, indem es den HTTP-Anfrage-Header „Accept-Language“ verwendet und diesen mit einer der verfügbaren, im Storefront-Kanal konfigurierten Spracheinstellungen abgleicht. Ist die ermittelte Spracheinstellung für den Kanal nicht verfügbar, verwendet Catalyst die als Standard festgelegte Spracheinstellung.

Das Catalyst-Routing-System unterstützt in Verbindung mit der Next.js App Router Internationalization-Bibliothek ein optionales URL-Segment zur Festlegung der Ländereinstellung:

mystore.com/fr/my-product

Ein Benutzer, dessen erkannte Spracheinstellung von der Standardeinstellung abweicht, wird auf eine URL wie die oben genannte weitergeleitet. Bei direktem Aufruf der URL legt das explizite URL-Segment ebenfalls den entsprechenden Sprachkontext fest. Unabhängig davon, ob die Spracheinstellung automatisch erkannt, durch die Standard-Spracheinstellung des Online-Shops festgelegt oder explizit in der Anfrage-URL angegeben wird, ist der festgelegte Sprachkontext über den Next.js-Parameter [locale] verfügbar.

Weitere Informationen zur Erkennung der Spracheinstellung finden Sie in den folgenden Dateien:

  • middlewares/with-intl.ts – Die anfängliche Erkennung der Ländereinstellung mit dem Next.js App Router Internationalization erfolgt hier, wobei der Kontext durch die Ländereinstellungskonfiguration zur Erstellungszeit bereitgestellt wird.
  • middlewares/with-routes.ts – Wir haben bereits gesehen, welche Rolle diese Datei bei der Weiterleitung einer Anfrage an ihr endgültiges Ziel spielt. Dazu gehört auch die explizite Einbindung des Ländereinstellungssegments in die umgeschriebene URL.

Sprach- und Währungsumschalter

Standardmäßig integriert Catalyst einen Sprachumschalter und einen Währungsumschalter in die Kopfzeile der Website, sofern mehrere Sprachen oder Währungen verfügbar sind. Die konfigurierten Sprachumgebungen und Währungen werden in diese Umschalter auf dem Storefront-Kanal übernommen. Daher hängen die verfügbaren Sprachumgebungen von der Konfiguration zum Zeitpunkt der Erstellung ab, und der Sprachumschalter nutzt das URL-Segment wie oben beschrieben.

Lokalisierung von statischem Text

In diesem Abschnitt erfahren Sie, wie Catalyst den statischen Text, der Teil Ihrer Catalyst-Anwendung ist, in die Sprache des Kunden übersetzt.

Speichern von Übersetzungen

In Ihrem Catalyst-Verzeichnis befindet sich ein Unterverzeichnis „/messages/“, das für die Lokalisierung verwendet wird. Jede Sprachdatei in diesem Verzeichnis entspricht einer Sprachumgebung, z. B. „/messages/en.json“. Diese Datei enthält die englischen Standardphrasen.

Für jede Sprache, die Sie unterstützen möchten, muss eine eigene JSON-Datei vorhanden sein. Außerdem müssen Sie jede Sprachdatei gemäß der BCP 47-Spezifikation für Sprachkennungen und Länder- oder Regionscodes benennen.

Jede Übersetzungsdatei muss außerdem Schlüssel-Wert-Paare enthalten. Daher können Sie Übersetzungen auf der Grundlage vordefinierter Schlüssel definieren, die zur Übersetzung der grundlegenden E-Commerce-Funktionen des Catalyst-Storefronts verwendet werden. Diese übersetzten Werte werden den Käufern als statische Zeichenfolgenübersetzungen angezeigt. Es ist gängige Praxis, die vorhandene Datei „en.json“ als Vorlage für das Schema zu verwenden. Die Datei „en.json“ enthält beispielsweise die folgenden Übersetzungsschlüssel und die dazugehörigen englischen Zeichenfolgen:

"ChangePassword": {
    "title": "Change password",
    "newPassword": "New password",
    "confirmPassword": "Confirm password",
    "passwordUpdated": "Password has been updated successfully!",
    "somethingWentWrong": "Something went wrong. Please try again later."
},

Verwendung von Schlüsseln in React-Komponenten

Schauen wir uns nun an, wie Server- und Client-Komponenten Übersetzungen verwenden. Das folgende Beispiel zeigt, wie eine Server-Komponente Übersetzungen nutzt. Der Aufruf von getTranslations() mit der Locale und dem „Namespace“ ruft die übersetzten Schlüssel-Wert-Paare aus der entsprechenden Übersetzungsdatei ab.

import { getTranslations } from 'next-intl/server';
...
export default async function ChangePassword({ params, searchParams }: Props) {
    ...
    const t = await getTranslations('Auth.ChangePassword');
    ...
    return (
        <ResetPasswordSection
            ...
            confirmPasswordLabel = { t('confirmPassword') }
            newPasswordLabel = { t('newPassword') }
            title = { t('title') }
        />
    );
}

Client-Komponenten hingegen handhaben die Übersetzung etwas anders. In der Stammdatei „app/[locale]layout.tsx“ wird ein „NextIntlClientProvider“ eingerichtet, der für die entsprechenden Hooks der Client-Komponenten erforderlich ist. Anschließend verwenden die Client-Komponenten die Methode „useTranslations“, um statischen Text zu übersetzen:

import { useTranslations } from 'next-intl';
export function ProductFaqs({
    ...
}: {
    ...
}) {
    ...
    const t = useTranslations('Components.Footer');
    ...
    return allFaqs.length <= 0 ? '' : (
        <section ...>
            <div ...>
                <h2 ...>
                    { t('heading') }
                </h2>
                ...
            </div>
        </section>
    );
}

Lokalisierung dynamischer Inhalte

Der Großteil der Texte, die Ihren Kunden angezeigt werden, stammt nicht aus statischen Zeichenfolgen in Ihrem Code, sondern aus Ihren Katalogdaten, CMS-Inhalten oder anderen Merchandising-Integrationen. Die Lokalisierungsstrategie hängt zwar von den Funktionen und Möglichkeiten der Anbieter ab, die Sie für Ihre Inhalte nutzen, doch hier werden wir die Mehrsprachen- und Mehrlokalitätsfunktionen besprechen, die in den integrierten Datenquellen von Catalyst verfügbar sind.

BigCommerce-Daten

Sie geben die Details zu Ihren BigCommerce-Katalogdaten in der Standardsprache Ihres Shops ein, können für diese Inhalte jedoch sprachspezifische Überschreibungen vornehmen. Mithilfe der GraphQL-Admin-API ist es möglich, grundlegende Produktinformationen, SEO-Informationen, Verfügbarkeit und weitere Details für eine bestimmte Ländereinstellung festzulegen.

Catalyst legt den Länderkontext von Abfragen an die GraphQL-Storefront-API mithilfe des Request-Headers „Accept-Language“ fest, sodass alle gerenderten Inhalte in der bevorzugten Sprache des Kunden angezeigt werden, sofern diese vorhanden ist. Dies stellt beispielsweise auch sicher, dass Warenkorbdaten der richtigen Ländereinstellung zugeordnet werden.

Der Accept-Language-Header wird in der Datei „client/index.ts“ festgelegt.

Makeswift-Inhalte

Ähnlich wie bei Katalogdaten ermittelt Catalyst den Sprachkontext, wenn Seiteninhalte geladen werden, die vom Makeswift-Visual-Editor verwaltet werden. Wenn Sie eine Makeswift-Website erstellen, werden die anfänglichen Sprachkontexte so festgelegt, dass sie mit den verfügbaren Sprachen des Online-Shops übereinstimmen. Anschließend können Sie die verfügbaren Sprachkontexte in den Website-Einstellungen konfigurieren.

Mit dem Sprachumschalter des Editors lassen sich nicht nur Texte an bestimmte Sprachversionen anpassen, sondern auch Aspekte des Layouts und der Sichtbarkeit von Inhalten.

Multi-Storefront

Eine Alternative zur Mehrsprachigkeit auf einem einzigen Storefront-Kanal ist die Einrichtung separater Kanäle für verschiedene Ländereinstellungen. Dies kann erforderlich sein, wenn sich nicht nur die Sprache unterscheidet. Wenn sich das Produktangebot, die Kategoriestruktur, die verfügbaren Währungen oder die verfügbaren Versandarten je nach Ländereinstellung unterscheiden, ist Multi-Storefront wahrscheinlich die ideale Strategie.

Pfadbasiert

Catalyst bietet integrierte Unterstützung für die Zuordnung eines Locale-Pfads zu einem bestimmten Kanal. Das folgende Beispiel in der Datei „channels.config.ts“ ordnet den Unterpfad „/fr“ der Kanal-ID 12345 zu:

const localeToChannelsMappings: Record<string, string> = {
    fr: '12345',
};

Sobald diese Zuordnung eingerichtet ist, sendet Catalyst, sobald es Französisch als Sprache erkennt (beispielsweise beim Aufruf einer URL wie mystore.com/fr/my-product), API-Anfragen an die von Ihnen angegebene BigCommerce-Kanal-ID.

Domänenbasiert

Wenn Ihre eigene Konfiguration erfordert, dass jede Storefront auf einer eigenen Domäne läuft, gibt es mehrere Möglichkeiten, dies zu realisieren. Im einfachsten Fall sollte jede Domäne auf eine separate Produktionsbereitstellung von Catalyst verweisen, wobei unterschiedliche Umgebungskonfigurationen die korrekte Zuordnung zum Storefront-Kanal gewährleisten:

Andererseits kann es sein, dass Ihre Anforderungen eine einzige Bereitstellung erfordern, die mehrere Domänen abdeckt:

Catalyst verfügt zwar nicht über integrierte Werkzeuge für ein echtes Multi-Tenant-Szenario wie dieses, doch lässt sich dies durch Anpassungen realisieren. Weitere Informationen finden Sie in diesem Vercel-Leitfaden und in der Beispiel-Multi-Tenant-App.

Zu den in Betracht zu ziehenden Schritten gehören voraussichtlich:

  • Zunächst erstellen Sie ein dynamisches Routensegment für die [Domain] ähnlich wie für [locale], wie in der Beispiel-App gezeigt.
  • Anschließend legen Sie das URL-Segment für die Domain mithilfe von Middleware fest, wie in der Beispiel-App gezeigt.
  • Zuletzt greifen Sie auf den Routenparameter der Domain zu und verwenden ihn, um die Kanal-ID dort bedingt festzulegen, wo der API-Client zum Einsatz kommt.

Bitte kontaktieren Sie uns unter manish@bay20.com oder rufen Sie uns unter +91-8800519180 / +91-9582784309 an, wenn Sie Unterstützung im Zusammenhang mit Bigcommerce benötigen. Sie können auch die Bigcommerce-Entwicklungsseite besuchen, um sich über unsere Dienstleistungen zu informieren.