Mehrsprachige Suche in Magento-Shops konfigurieren

1. Warum mehrsprachige Suche mehr als Uebersetzung ist

Mehrsprachige Suche wird in vielen Magento-Projekten unterschaetzt, weil sie auf den ersten Blick wie ein reines Uebersetzungsproblem aussieht: Produktnamen und Beschreibungen werden pro Store View uebersetzt, und die Suche funktioniert scheinbar automatisch in jeder Sprache. Tatsaechlich steckt hinter funktionierender mehrsprachiger Suche deutlich mehr als uebersetzter Content: Jede Sprache hat eigene grammatikalische Regeln, eigene Wortbildungsmuster und eigene Stoppwortlisten, die alle in die Analyzer-Konfiguration des Suchindex einfliessen muessen.

Ein englischer Standard-Analyzer, der auf deutsche Produktbeschreibungen angewendet wird, erkennt zusammengesetzte Woerter wie "Laufschuhe" nicht als Kombination aus "Lauf" und "Schuhe" und kann deshalb keine sinnvollen Teiltreffer liefern. Umgekehrt fuehrt ein deutscher Analyzer auf franzoesischem Content zu falschen Stemming-Ergebnissen, weil die Wortendungen und Flexionsregeln beider Sprachen grundverschieden sind. Mehrsprachige Suche erfordert deshalb, dass jede Sprache technisch als eigener Suchkontext behandelt wird, nicht nur als eigene Textvariante.

Dieser Artikel zeigt, wie mehrsprachige Suche in Magento technisch sauber aufgebaut wird: von der Store-View-basierten Indexstruktur ueber sprachspezifische Analyzer bis zu den typischen Fehlern, die zu vermischten oder falschen Suchergebnissen fuehren.

2. Store-View-basierte Index-Namensgebung

Magento legt fuer jede Store View einen eigenen Elasticsearch-Index an, typischerweise im Muster magento2_product_<store_id>_v<version> mit einem Alias ohne Versionssuffix fuer den produktiven Zugriff. Diese Trennung ist die technische Grundvoraussetzung fuer mehrsprachige Suche: Jede Sprache erhaelt einen eigenen, physisch getrennten Index, sodass unterschiedliche Mapping-Konfigurationen, insbesondere unterschiedliche Analyzer, pro Sprache moeglich sind, ohne sich gegenseitig zu beeinflussen.

Diese Trennung ist notwendig, aber allein nicht ausreichend. Ohne zusaetzliche Analyzer-Konfiguration verwendet jeder Store-View-Index denselben generischen Standard-Analyzer, unabhaengig von der tatsaechlichen Sprache des Contents. Das bedeutet: Selbst mit korrekt getrennten Indizes pro Store View bleibt mehrsprachige Suche unzureichend, solange nicht zusaetzlich jeder Index mit dem zur jeweiligen Sprache passenden Analyzer konfiguriert wird.

# List all product search indices to verify per-store-view separation
curl -s -X GET "https://localhost:9200/_cat/indices/magento2_product_*?v"

# Show which alias points to which physical index for store id 2 (e.g. French)
curl -s -X GET "https://localhost:9200/_alias/magento2_product_2"

3. Sprachspezifische Analyzer: Stemmer, Stopwords, Normalisierung

Elasticsearch liefert vorgefertigte, sprachspezifische Analyzer fuer eine grosse Zahl von Sprachen, jeweils mit passendem Stemmer, passender Stopwortliste und passenden Normalisierungsregeln. Der german-Analyzer kennt beispielsweise deutsche Flexionsformen und reduziert "Laufschuhe", "Laufschuh" und "Laufschuhen" auf denselben Wortstamm, waehrend der french-Analyzer eigene Regeln fuer Akzente und franzoesische Elisionen mitbringt. Diese Analyzer sind die Grundlage jeder funktionierenden mehrsprachigen Suche, weil sie sicherstellen, dass grammatikalische Varianten eines Wortes zuverlaessig demselben Suchtreffer zugeordnet werden.

Der Stemmer ist dabei nur eine von drei zentralen Komponenten. Die sprachspezifische Stopwortliste filtert haeufige Fuellwoerter wie "und", "der", "die" im Deutschen oder "and", "the" im Englischen heraus, die sonst die Relevanzberechnung verfaelschen wuerden. Die Normalisierung behandelt sprachspezifische Schreibvarianten, etwa Umlaute im Deutschen oder Akzentzeichen im Franzoesischen, sodass eine Suche nach "Muhle" auch "Muehle" oder "Mühle" findet, je nach gewaehlter Normalisierungsstrategie.

PUT /magento2_product_2_v1
{
  "settings": {
    "analysis": {
      "filter": {
        "german_stemmer": { "type": "stemmer", "language": "light_german" },
        "german_stop": { "type": "stop", "stopwords": "_german_" }
      },
      "analyzer": {
        "german_product_analyzer": {
          "type": "custom",
          "tokenizer": "standard",
          "filter": ["lowercase", "german_stop", "german_normalization", "german_stemmer"]
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "name": { "type": "text", "analyzer": "german_product_analyzer" },
      "description": { "type": "text", "analyzer": "german_product_analyzer" }
    }
  }
}

4. Locale-zu-Analyzer-Mapping in Magento konfigurieren

Magento kennt die Locale jeder Store View bereits ueber die Konfiguration general/locale/code, etwa de_DE, en_US oder fr_FR. Fuer eine saubere mehrsprachige Suche lohnt es sich, diese vorhandene Information systematisch mit dem passenden Elasticsearch-Analyzer zu verknuepfen, statt fuer jede Sprache manuell ein separates Mapping zu pflegen. Ein praktischer Ansatz ist eine Mapping-Tabelle, die Locale-Codes auf Analyzer-Namen abbildet und beim Aufbau des Index-Settings-Requests herangezogen wird.

Diese Zuordnung laesst sich als eigene Konfigurationsklasse implementieren, die vor jedem Full-Reindex das passende Analyzer-Setting fuer die jeweilige Store View bestimmt. Der Vorteil dieses Ansatzes: Neue Store Views mit bereits unterstuetzten Sprachen benoetigen keine manuelle Analyzer-Konfiguration, weil die Zuordnung automatisch aus der Locale abgeleitet wird. Nur fuer neue, bisher nicht abgedeckte Sprachen muss die Mapping-Tabelle einmalig erweitert werden.

<?php
declare(strict_types=1);

namespace Mironsoft\SearchExtension\Model\Adapter;

/**
 * Maps a Magento store locale code to the matching Elasticsearch
 * language analyzer, used when building per-store index settings.
 */
class LocaleAnalyzerResolver
{
    /**
     * @var array<string, string>
     */
    private const LOCALE_TO_ANALYZER = [
        'de_DE' => 'german_product_analyzer',
        'de_AT' => 'german_product_analyzer',
        'en_US' => 'english_product_analyzer',
        'en_GB' => 'english_product_analyzer',
        'fr_FR' => 'french_product_analyzer',
    ];

    private const DEFAULT_ANALYZER = 'standard';

    /**
     * Resolves the analyzer name for a given Magento locale code.
     *
     * @param string $localeCode
     * @return string
     */
    public function resolve(string $localeCode): string
    {
        return self::LOCALE_TO_ANALYZER[$localeCode] ?? self::DEFAULT_ANALYZER;
    }
}

5. Cross-Language-Relevanz-Bleed vermeiden

Ein subtiles, aber haeufiges Problem bei mehrsprachiger Suche ist der sogenannte Cross-Language-Relevanz-Bleed: Suchbegriffe aus einer Sprache liefern unerwartete Treffer in einem Index einer anderen Sprache, weil beide denselben generischen Analyzer verwenden. Ohne sprachspezifische Trennung kann eine deutsche Suchanfrage im englischen Store-View-Index technisch funktionieren, liefert aber schlechte Relevanz, weil englische Stemming-Regeln auf deutsche Flexionsformen falsch angewendet werden.

Der zuverlaessige Schutz gegen Cross-Language-Bleed ist die konsequente Kombination aus store-view-spezifischen Indizes und store-view-spezifischen Analyzern, wie in den vorherigen Abschnitten beschrieben. Zusaetzlich sollte die Suchanfrage selbst niemals ueber mehrere Sprach-Indizes gleichzeitig laufen, es sei denn, dies ist explizit gewuenscht, etwa bei einer globalen Cross-Store-Suche. Eine versehentliche Query gegen einen Wildcard-Indexpattern wie magento2_product_* statt gegen den spezifischen Store-View-Alias ist eine haeufige, leicht uebersehene Ursache fuer Cross-Language-Bleed in der Praxis.

6. Sonderfaelle: Komposita und CJK-Sprachen

Deutsch und aehnliche Sprachen mit produktiver Kompositabildung stellen eine besondere Herausforderung fuer mehrsprachige Suche dar. Ein zusammengesetztes Wort wie "Fahrradhelm" sollte idealerweise sowohl als Ganzes als auch in seinen Bestandteilen "Fahrrad" und "Helm" durchsuchbar sein, damit eine Suche nach "Helm" auch Fahrradhelme findet. Der german-Analyzer bietet mit dem decompound-Filter eine Loesung, die zusammengesetzte Woerter automatisch in sinnvolle Teilworte zerlegt, basierend auf einem Woerterbuch.

Noch groesser ist die Herausforderung bei CJK-Sprachen wie Chinesisch, Japanisch und Koreanisch, die keine Leerzeichen zwischen Woertern verwenden. Der Standard-Tokenizer von Elasticsearch, der auf Whitespace basiert, funktioniert fuer diese Sprachen nicht. Stattdessen werden spezialisierte Plugins wie kuromoji fuer Japanisch oder smartcn fuer Chinesisch benoetigt, die eine sprachspezifische Wortsegmentierung durchfuehren, bevor ueberhaupt eine sinnvolle mehrsprachige Suche fuer diese Maerkte moeglich ist. Diese Plugins muessen separat auf dem Elasticsearch-Cluster installiert werden und sind nicht Teil der Standardinstallation.

7. Synonyme pro Sprache verwalten

Synonym-Listen fuer mehrsprachige Suche muessen zwingend pro Sprache getrennt gepflegt werden, weil dieselben Konzepte in unterschiedlichen Sprachen unterschiedliche Wortfamilien bilden. Das deutsche Synonympaar "Kopfhoerer" und "Headset" hat im Englischen mit "headphones" und "headset" eine eigene, nicht direkt uebertragbare Entsprechung. Eine gemeinsame, sprachuebergreifende Synonymliste fuehrt fast zwangslaeufig zu falschen oder fehlenden Verknuepfungen in mindestens einer der beteiligten Sprachen.

Technisch wird dies ueber separate synonym-Filter je Analyzer geloest, die auf sprachspezifische Synonym-Dateien verweisen. Diese Dateien lassen sich entweder statisch als Teil der Index-Settings pflegen oder ueber die Synonym-API von Elasticsearch dynamisch aktualisieren, ohne einen vollstaendigen Reindex auszuloesen. Fuer mehrsprachige Suche mit haeufig wechselnden Synonymen, etwa saisonalen Marketingbegriffen, ist die dynamische Variante die deutlich praktischere Wahl.

8. Mehrsprachige Suchqualitaet testen

Das Testen von mehrsprachiger Suche erfordert sprachspezifische Testfaelle, nicht nur eine uebersetzte Kopie derselben Testqueries. Ein Testset fuer den deutschen Store View sollte gezielt Komposita, Umlaut-Varianten und typische deutsche Flexionsformen abdecken, waehrend ein franzoesisches Testset Akzentvarianten und Elisionen pruefen sollte. Nur so lassen sich sprachspezifische Regressionen erkennen, die bei einem rein uebersetzten Testset unbemerkt bleiben wuerden.

Ein einfacher, aber wirksamer Test ist der Vergleich der Trefferzahl fuer semantisch aequivalente Anfragen in verschiedenen Schreibvarianten, etwa "Muehle" versus "Mühle" im Deutschen. Liefern beide Varianten dieselbe Trefferzahl, funktioniert die Normalisierung korrekt. Weichen die Zahlen deutlich voneinander ab, deutet das auf ein fehlerhaftes oder fehlendes Analyzer-Setting fuer diese Sprache hin.

9. Praxisbeispiel: DE/EN/FR-Shop mit eigenen Analyzern

Ein realistisches Beispiel: Ein Shop betreibt drei Store Views fuer Deutschland, die USA und Frankreich. Ohne mehrsprachige Suche-Konfiguration nutzen alle drei denselben Standard-Analyzer, was insbesondere im deutschen Store View zu schlechter Trefferqualitaet bei Komposita fuehrt. Die Loesung kombiniert drei Massnahmen: erstens die bereits vorhandene store-view-basierte Indextrennung, zweitens je Store View einen passenden Sprach-Analyzer mit decompound-Filter fuer Deutsch, und drittens sprachspezifische Synonymlisten, die ueber den LocaleAnalyzerResolver automatisch dem richtigen Index zugeordnet werden.

Nach der Umstellung zeigt sich der Effekt am deutlichsten bei Komposita-Suchen: Eine Suche nach "Helm" im deutschen Store View findet nun auch "Fahrradhelm" und "Skihelm", waehrend die englische und franzoesische Suche unveraendert praezise bleiben, weil sie ihre eigenen, unabhaengigen Analyzer-Konfigurationen nutzen. Dieses Beispiel zeigt, dass mehrsprachige Suche kein einmaliges Setup ist, sondern eine fortlaufende Pflege sprachspezifischer Analyzer- und Synonym-Konfigurationen erfordert, sobald neue Maerkte hinzukommen.

10. Zusammenfassung

Funktionierende mehrsprachige Suche in Magento entsteht aus dem Zusammenspiel zweier Ebenen: der store-view-basierten Indextrennung, die Magento bereits standardmaessig mitbringt, und einer bewussten sprachspezifischen Analyzer-Konfiguration, die zusaetzlich aufgesetzt werden muss. Ohne diese zweite Ebene bleibt die Trennung wirkungslos, weil alle Indizes denselben generischen Analyzer verwenden und damit weder Komposita noch sprachspezifische Flexionsformen korrekt verarbeiten.

Wer mehrsprachige Suche fuer mehr als zwei, drei europaeische Sprachen plant, sollte fruehzeitig Sonderfaelle wie CJK-Sprachen und Kompositabildung einplanen, sprachspezifische Synonymlisten getrennt pflegen und mit sprachspezifischen Testfaellen kontinuierlich pruefen, dass keine Cross-Language-Vermischung auftritt. Diese Disziplin verhindert, dass internationale Expansion zu leise verschlechterten Suchergebnissen in einzelnen Maerkten fuehrt.

11. FAQ: Mehrsprachige Suche in Magento