Magento 2 Mehrsprachige Produktattribute verwalten

1. Wo mehrsprachige Produktattribute wirklich beginnen

Sobald ein Magento-2-Shop Produkte in mehr als einer Sprache anbietet, wird die Verwaltung von mehrsprachigen Produktattributen zu einer der Aufgaben, die technisch einfach aussehen, aber organisatorisch schnell komplex werden. Magento speichert Attributwerte im EAV-Modell, Entity-Attribute-Value, wobei jeder Wert einer bestimmten Entity-ID, einem bestimmten Attribut und einem bestimmten Store zugeordnet ist. Für übersetzbare Felder wie Produktname oder Beschreibung bedeutet das: derselbe Produktdatensatz kann pro Store view einen komplett anderen Text tragen, ohne dass ein zweites Produkt angelegt werden muss.

Die eigentliche Herausforderung liegt nicht in der Datenbankstruktur selbst, sondern im Zusammenspiel aus Attribut-Scope-Konfiguration, Fallback-Verhalten und dem redaktionellen Prozess, der sicherstellt, dass wirklich jedes Attribut in jeder Sprache gepflegt wird. Fehlt eine Übersetzung, zeigt Magento standardmäßig den Wert des Default-Stores an, was auf den ersten Blick harmlos wirkt, aber bei mehrsprachigen Katalogen mit tausenden Produkten zu Situationen führt, in denen englische Produktnamen in einem französischen Store view auftauchen, ohne dass ein technischer Fehler vorliegt.

2. EAV-Attribut-Scope: Global, Website, Store View

Jedes Produktattribut in Magento besitzt eine Scope-Einstellung mit drei möglichen Werten: Global, Website oder Store View. Nur Attribute mit Scope Store View können tatsächlich pro Sprache unterschiedliche Werte tragen, technische Attribute wie SKU oder Gewicht sind dagegen meist Global gesetzt, weil sie unabhängig von der Sprache identisch bleiben müssen. Für mehrsprachige Produktattribute wie Name, Beschreibung, Kurzbeschreibung und Meta-Daten ist Store-View-Scope die einzig sinnvolle Einstellung, da diese Inhalte per Definition sprachabhängig sind.

Ein häufiger Konfigurationsfehler entsteht, wenn ein eigentlich übersetzbares Attribut versehentlich auf Website-Scope statt Store-View-Scope gesetzt wird. In diesem Fall lassen sich zwar unterschiedliche Werte pro Website pflegen, aber nicht pro Store view innerhalb derselben Website, was bei Ländern mit mehreren Sprachen auf einer gemeinsamen Website, etwa Belgien mit Niederländisch und Französisch, sofort zum Problem wird. Der Scope eines bestehenden Attributs lässt sich zwar nachträglich ändern, erfordert aber eine vollständige Neuindizierung und sollte vor dem produktiven Einsatz sorgfältig geplant werden.

<?php

declare(strict_types=1);

namespace Mironsoft\ProductTranslation\Setup\Patch\Data;

use Magento\Eav\Setup\EavSetup;
use Magento\Eav\Setup\EavSetupFactory;
use Magento\Framework\Setup\ModuleDataSetupInterface;
use Magento\Framework\Setup\Patch\DataPatchInterface;
use Magento\Catalog\Model\Product;

/**
 * Adds a store-view-scoped attribute for a translated marketing headline.
 */
final class AddMarketingHeadlineAttribute implements DataPatchInterface
{
    /**
     * @param ModuleDataSetupInterface $moduleDataSetup Setup connection wrapper
     * @param EavSetupFactory $eavSetupFactory Creates EAV setup helper instances
     */
    public function __construct(
        private readonly ModuleDataSetupInterface $moduleDataSetup,
        private readonly EavSetupFactory $eavSetupFactory
    ) {
    }

    /**
     * Create the translatable "marketing_headline" attribute with store view scope.
     *
     * @return void
     */
    public function apply(): void
    {
        $this->moduleDataSetup->getConnection()->startSetup();

        /** @var EavSetup $eavSetup */
        $eavSetup = $this->eavSetupFactory->create(['setup' => $this->moduleDataSetup]);

        $eavSetup->addAttribute(
            Product::ENTITY,
            'marketing_headline',
            [
                'type' => 'varchar',
                'label' => 'Marketing Headline',
                'input' => 'text',
                'required' => false,
                'global' => \Magento\Eav\Model\Entity\Attribute\ScopedAttributeInterface::SCOPE_STORE,
                'group' => 'General',
                'visible' => true,
                'used_in_product_listing' => true,
            ]
        );

        $this->moduleDataSetup->getConnection()->endSetup();
    }

    /**
     * @return array Dependencies executed before this patch
     */
    public static function getDependencies(): array
    {
        return [];
    }

    /**
     * @return array Aliases for this patch
     */
    public function getAliases(): array
    {
        return [];
    }
}

3. Der Fallback-Mechanismus im Detail

Der Fallback-Mechanismus für mehrsprachige Produktattribute ist in der Tabelle catalog_product_entity_varchar und ihren Geschwistertabellen für andere Datentypen technisch verankert: Ein Wert mit store_id = 0 gilt als globaler Default-Wert, Werte mit einer konkreten store_id überschreiben diesen Default für den jeweiligen Store view. Existiert für einen Store view kein spezifischer Eintrag, liest Magento automatisch den Wert mit store_id = 0 und zeigt ihn an, ohne dass dies im Backend als fehlende Übersetzung markiert wird.

Dieses Verhalten ist bewusst so gestaltet, weil es verhindert, dass ein Produkt ganz ohne Titel angezeigt wird, nur weil eine Übersetzung noch aussteht. Der Nachteil: Ohne einen zusätzlichen Kontrollmechanismus bleibt unsichtbar, welche Produkte in welcher Sprache tatsächlich vollständig übersetzt sind und welche lediglich auf den Default-Wert zurückfallen. Für Redaktionsteams, die systematisch prüfen müssen, ob alle mehrsprachigen Produktattribute gepflegt sind, reicht die Standard-Produktansicht im Backend daher nicht aus.

-- Find products where the French store view (store_id = 4) has no
-- explicit name override and therefore falls back to store_id = 0
SELECT e.entity_id, e.sku
FROM catalog_product_entity e
WHERE NOT EXISTS (
    SELECT 1
    FROM catalog_product_entity_varchar v
    INNER JOIN eav_attribute a ON a.attribute_id = v.attribute_id
    WHERE a.attribute_code = 'name'
      AND v.entity_id = e.entity_id
      AND v.store_id = 4
);

-- Count translation completeness per store for the "description" attribute
SELECT v.store_id, COUNT(DISTINCT v.entity_id) AS translated_products
FROM catalog_product_entity_varchar v
INNER JOIN eav_attribute a ON a.attribute_id = v.attribute_id
WHERE a.attribute_code = 'description'
GROUP BY v.store_id;

4. Eigenes übersetzbares Attribut per Setup-Patch anlegen

Für ein neues, eigenes Attribut, das mehrsprachige Produktattribute um marketingrelevante Inhalte erweitert, etwa eine kampagnenspezifische Überschrift, ist ein Data Patch der saubere Weg. Entscheidend ist die Einstellung global mit dem Wert ScopedAttributeInterface::SCOPE_STORE, die das Attribut auf Store-View-Ebene übersetzbar macht. Ohne diese explizite Angabe würde Magento das Attribut standardmäßig auf globalen Scope setzen, was für Übersetzungszwecke ungeeignet ist.

Nach dem Anlegen eines solchen Attributs sollte im Admin-Backend geprüft werden, ob es tatsächlich in jedem Store view separat editierbar ist, sichtbar am Store-View-Umschalter oberhalb des Eingabefelds im Produktformular. Diese visuelle Bestätigung ist der schnellste Weg, um einen falsch konfigurierten Scope zu erkennen, bevor Content-Redakteure beginnen, Übersetzungen einzupflegen, die später durch eine Scope-Korrektur wieder verloren gehen könnten.

5. CSV-Import mit Store-View-Spalte

Für die Massenpflege von mehrsprachigen Produktattributen ist der native Produkt-Import über bin/magento beziehungsweise das Backend-Import-Tool der praktikabelste Weg. Die CSV-Datei benötigt dafür eine Spalte store_view_code, die pro Zeile angibt, für welchen Store view die restlichen Spaltenwerte gelten. Eine Zeile ohne store_view_code, oder mit einem leeren Wert, schreibt in den globalen Default-Wert mit store_id = 0, während eine Zeile mit gesetztem Code, etwa fr, ausschließlich die Store-View-spezifische Übersetzung schreibt.

Ein häufiger Fehler beim CSV-Import ist die Annahme, dass für jede Sprache eine vollständig separate CSV-Zeile mit allen Attributen nötig ist. Tatsächlich genügt für eine reine Übersetzungszeile die Angabe von SKU, store_view_code und den zu übersetzenden Attributen, alle anderen Attribute bleiben leer und werden nicht überschrieben. Wer versehentlich alle Spalten mit leeren Werten in einer Übersetzungszeile mitführt, riskiert, dass Import-Tools diese leeren Werte als bewusste Löschung interpretieren, abhängig von der gewählten Import-Verhaltensweise.

sku,store_view_code,name,description,short_description
WIDGET-001,,Widget (Default),"Default English description",Short default text
WIDGET-001,fr,Widget Français,"Description en français complète",Texte court en francais
WIDGET-001,de,Widget Deutsch,"Vollstaendige deutsche Beschreibung",Kurzer deutscher Text

# Import via CLI, dry-run first to catch mapping errors before writing
bin/magento catalog:products:import --behavior=append --file=translations.csv --dry-run
bin/magento catalog:products:import --behavior=append --file=translations.csv

6. Programmatische Übersetzungspflege mit DataPatch

Für Übersetzungen, die Teil eines versionierten Deployments sein sollen, etwa initiale Katalogdaten für einen neuen Markt, ist ein Data Patch die robustere Alternative zum CSV-Import. Ein solcher Patch lädt das Produkt über das Repository, setzt den Store-Kontext explizit und speichert die übersetzte Attributversion gezielt für den jeweiligen Store view. Diese Methode ist zwar aufwändiger als ein CSV-Import, aber vollständig versioniert und reproduzierbar über Umgebungen hinweg, was für mehrsprachige Produktattribute in CI/CD-Pipelines entscheidend ist.

Ein wichtiges Detail: Der ProductRepositoryInterface::save()-Aufruf muss mit einem Produkt erfolgen, das explizit über setStoreId() im gewünschten Store-Kontext geladen wurde, sonst schreibt Magento die Änderung versehentlich in den Default-Scope statt in den gewünschten Store view. Dieser Fehler ist einer der häufigsten bei der programmatischen Pflege mehrsprachiger Inhalte und schwer zu debuggen, weil die Speicherung selbst ohne Fehlermeldung erfolgreich verläuft.

<?php

declare(strict_types=1);

namespace Mironsoft\ProductTranslation\Setup\Patch\Data;

use Magento\Catalog\Api\ProductRepositoryInterface;
use Magento\Framework\Setup\Patch\DataPatchInterface;
use Magento\Store\Api\StoreRepositoryInterface;

/**
 * Sets an initial French translation for the marketing headline attribute.
 */
final class TranslateMarketingHeadlineFr implements DataPatchInterface
{
    /**
     * @param ProductRepositoryInterface $productRepository Loads/saves products
     * @param StoreRepositoryInterface $storeRepository Resolves the "fr" store view
     */
    public function __construct(
        private readonly ProductRepositoryInterface $productRepository,
        private readonly StoreRepositoryInterface $storeRepository
    ) {
    }

    /**
     * @return void
     * @throws \Magento\Framework\Exception\NoSuchEntityException
     * @throws \Magento\Framework\Exception\CouldNotSaveException
     */
    public function apply(): void
    {
        $frStore = $this->storeRepository->get('fr');

        // WRONG: loading without setStoreId() writes back to store_id = 0
        // $product = $this->productRepository->get('WIDGET-001');

        // RIGHT: explicitly load in the target store context
        $product = $this->productRepository->get('WIDGET-001', false, (int) $frStore->getId());
        $product->setData('marketing_headline', 'Offre exclusive de rentree');

        $this->productRepository->save($product);
    }

    /**
     * @return array Dependencies executed before this patch
     */
    public static function getDependencies(): array
    {
        return [];
    }

    /**
     * @return array Aliases for this patch
     */
    public function getAliases(): array
    {
        return [];
    }
}

7. Kategorien und Static Blocks nicht vergessen

Die Diskussion um mehrsprachige Produktattribute konzentriert sich oft ausschließlich auf Produktdaten, dabei folgen Kategorienamen und Kategoriebeschreibungen demselben EAV-Fallback-Mechanismus. Ein häufig übersehener Fall: Die Navigation zeigt in einem nicht vollständig übersetzten Store view englische Kategorienamen neben französischen Produktnamen, was inkonsistent wirkt, aber technisch korrekt dem Fallback-Verhalten entspricht.

Statische Blöcke, etwa für Banner oder rechtliche Hinweise auf Kategorieseiten, sind technisch keine EAV-Attribute, sondern eigene CMS-Entitäten mit Store-Zuordnung über eine separate Zuordnungstabelle. Für sie gibt es keinen automatischen Fallback auf einen Default-Store, ein fehlender Block in einem Store view bleibt schlicht leer. Wer ein vollständiges mehrsprachiges Erlebnis anbieten will, muss also sowohl EAV-Attribute als auch CMS-Inhalte separat auf Vollständigkeit prüfen.

8. Übersetzungslücken systematisch aufspüren

Für Shops mit mehreren tausend Produkten und mehreren Sprachen ist eine manuelle Prüfung der Übersetzungsvollständigkeit nicht praktikabel. Ein eigenes Admin-Grid, das pro Attribut und Store view die Anzahl der tatsächlich übersetzten Produkte gegen die Gesamtzahl der Produkte stellt, ist der zuverlässigste Weg, Lücken bei mehrsprachigen Produktattributen systematisch aufzudecken. Ein solches Grid lässt sich mit einer eigenen Collection implementieren, die auf den zuvor gezeigten SQL-Abfragen basiert.

Für automatisierte Qualitätssicherung bietet sich zusätzlich ein Cron-Job an, der wöchentlich einen Übersetzungsreport per E-Mail an das Redaktionsteam versendet, sobald der Anteil unübersetzter Produkte in einem Store view einen definierten Schwellwert überschreitet. Diese proaktive Überwachung verhindert, dass Übersetzungslücken erst durch Kundenbeschwerden auffallen, wenn ein neuer Produktimport größere Mengen unübersetzter Artikel eingeführt hat.

<?php

declare(strict_types=1);

namespace Mironsoft\ProductTranslation\Model;

use Magento\Framework\App\ResourceConnection;

/**
 * Computes translation completeness ratios per store view and attribute.
 */
final class TranslationCompletenessReport
{
    /**
     * @param ResourceConnection $resourceConnection Direct DB access for reporting
     */
    public function __construct(
        private readonly ResourceConnection $resourceConnection
    ) {
    }

    /**
     * @param string $attributeCode e.g. "name" or "description"
     * @return array<int, array{store_id: int, translated: int, total: int}>
     */
    public function getCompletenessPerStore(string $attributeCode): array
    {
        $connection = $this->resourceConnection->getConnection();
        $select = $connection->select()
            ->from(['v' => 'catalog_product_entity_varchar'], ['store_id', 'translated' => 'COUNT(DISTINCT entity_id)'])
            ->joinInner(['a' => 'eav_attribute'], 'a.attribute_id = v.attribute_id', [])
            ->where('a.attribute_code = ?', $attributeCode)
            ->group('v.store_id');

        return $connection->fetchAll($select);
    }
}

9. Attribut-Scope-Strategien im Vergleich

Die folgende Übersicht zeigt, welcher Scope für unterschiedliche Attributtypen bei mehrsprachigen Produktattributen sinnvoll ist und welche Konsequenzen eine falsche Wahl hat.

Die Grundregel bleibt einfach: Alles, was ein Mensch liest und versteht, gehört auf Store-View-Ebene. Alles, was das System technisch identifiziert oder physikalisch misst, gehört auf globale Ebene. Diese Faustregel löst die überwiegende Mehrheit der Scope-Entscheidungen bei mehrsprachigen Produktattributen zuverlässig.

10. Zusammenfassung

Die Verwaltung mehrsprachiger Produktattribute in Magento 2 steht und fällt mit dem korrekten Attribut-Scope: Nur Attribute mit Store-View-Scope können tatsächlich pro Sprache unterschiedliche Werte tragen. Der Fallback-Mechanismus auf store_id = 0 verhindert leere Anzeigen, macht Übersetzungslücken aber unsichtbar, wenn keine zusätzliche Prüfung existiert. CSV-Import mit store_view_code-Spalte und Data Patches mit explizitem Store-Kontext sind die beiden robusten Wege, Übersetzungen zu pflegen.

Wer Kategorien und statische Blöcke bei der Übersetzungsplanung mitdenkt und ein systematisches Monitoring für Übersetzungsvollständigkeit einrichtet, vermeidet die häufigste Enttäuschung internationaler Rollouts: einen Katalog, der zwar technisch mehrsprachig konfiguriert ist, aber in der Praxis Lücken zeigt, die erst durch Kundenfeedback auffallen.

11. FAQ: Magento 2 Mehrsprachige Produktattribute