Die Shopify Translations API ermöglicht es Ihnen, alle Inhalte in Ihrem Shop (Produkttitel, Beschreibungen, Kategorieseiten, Blogbeiträge) direkt über GraphQL zu lesen und zu schreiben. Die DeepL API wandelt diese Inhalte mit professioneller maschineller Übersetzung um. Wenn Sie die beiden APIs kombinieren, erzielen Sie das gleiche Ergebnis, ohne monatlich 15-99 $ an Weglot oder Langify zu zahlen, und behalten die volle Kontrolle über die Übersetzung.
Dieser Leitfaden behandelt die technischen Schritte, GraphQL-Abfragen und den Automatisierungsablauf, die erforderlich sind, um Ihren Shopify-Shop mit DeepL in eine andere Sprache zu übersetzen. Sie müssen keine Anwendungen installieren.
Was ist die Shopify Translations API und wie funktioniert sie mit DeepL?
Die Shopify Translations API ist Teil der Admin GraphQL API und ermöglicht es Ihnen, Übersetzungen für jede „übersetzbare Ressource“ in Ihrem Shop zu speichern, zu lesen und zu löschen. Die DeepL API fungiert an dieser Stelle als Zwischenschicht: Sie nimmt den Rohinhalt von Shopify, sendet ihn an DeepL und schreibt die zurückgegebene Übersetzung zurück zu Shopify.
Shopify definiert die folgenden Typen als übersetzbare Ressourcen: PRODUCT, PRODUCT_VARIANT, COLLECTION, BLOG, ARTICLE, PAGE, SHOP, THEME, METAFIELD, LINK, FILTER. Die zu übersetzenden Felder sind für jede Ressource vordefiniert. Zum Beispiel sind für ein Produkt die Felder title, body_html, handle, meta_title, meta_description übersetzbar.
DeepL arbeitet über den Endpunkt /v2/translate. Im Anfragetext senden Sie die Ausgangssprache, die Zielsprache und den zu übersetzenden Text; der übersetzte Text wird in der JSON-Antwort zurückgegeben. Für HTML-Inhalte ist es zwingend erforderlich, den Parameter tag_handling=html hinzuzufügen; andernfalls würden Tags wie <p>, <strong>, <br> ebenfalls versucht zu übersetzen und beschädigt werden.
Bevor Sie beginnen: Anforderungen und Vorbereitung
Um diese Integration einzurichten, benötigen Sie vier Dinge: eine Shopify Custom App, die richtigen API-Berechtigungen, ein DeepL-Konto und ein aktives Locale für die Zielsprache in Shopify Markets. Wenn Sie neu in der grundlegenden Struktur von Shopify sind, empfehlen wir Ihnen zuerst Was ist Shopify unseren Inhalt zu lesen.
1. Shopify Custom App erstellen
Gehen Sie im Shopify Admin zu Settings > Apps and sales channels > Develop apps und folgen Sie dem Pfad. Erstellen Sie eine neue App. Aktivieren Sie im Bereich Admin API Configuration die folgenden Scopes:
- read_translations
- write_translations
- read_products (zum Abrufen von Produktinhalten)
- read_content (für Seiten- und Blog-Inhalte)
Installieren Sie die App und kopieren Sie den Admin API-Zugriffstoken. Dieser Token wird bei allen API-Aufrufen als X-Shopify-Access-Token-Header verwendet.
2. DeepL API-Schlüssel
DeepL API Eröffnen Sie ein kostenloses Konto. Der kostenlose Plan erlaubt Ihnen Übersetzungen von bis zu 500.000 Zeichen pro Monat. Für einen mittelgroßen Shopify-Shop deckt dieses Limit in der Regel eine einmalige vollständige Übersetzung ab; in den Folgemonaten sinkt der Verbrauch, da nur neu hinzugefügte Inhalte übersetzt werden. Holen Sie sich Ihren API-Schlüssel aus dem Kontopanel.
3. Locale-Aktivierung in Shopify Markets
Gehen Sie im Shopify Admin-Bereich zu Settings > Markets . Fügen Sie Ihre Zielsprache (z.B. de für Deutsch) dem entsprechenden Markt hinzu. Ohne hinzugefügte Locale schlägt die translationsRegister-Mutation fehl.
Wichtiger Hinweis: Shopify unterstützt gleichzeitig maximal 20 Locales. Shops mit einem Basisplan müssen möglicherweise die kostenpflichtige Funktion von Shopify Markets für zusätzliche Sprachen aktivieren. Shopify Plus-Kunden sind von dieser Einschränkung nicht betroffen.
Schritt-für-Schritt-Anleitung: DeepL + Shopify Übersetzungs-Workflow
Die Integration erfolgt in vier Schritten: Inhalte aus Shopify abrufen, an DeepL senden, Übersetzungen in Shopify schreiben und automatische Auslösung per Webhook.
1. Abrufen der zu übersetzenden Inhalte aus Shopify
Die translatableResources-Abfrage gibt alle übersetzbaren Felder eines bestimmten Ressourcentyps zurück. Die folgende GraphQL-Abfrage ruft die übersetzbaren Inhalte und vorhandenen Übersetzungen aller Produkte in Ihrem Shop ab:
query GetTranslatableProducts($after: String) {
translatableResources(resourceType: PRODUCT, first: 50, after: $after) {
edges {
node {
resourceId
translatableContent {
key
value
digest
locale
}
translations(locale: "de") {
key
value
outdatedAt
}
}
}
pageInfo {
hasNextPage
endCursor
}
}
}Das Feld digest ist von entscheidender Bedeutung. Es repräsentiert den Hash jedes Inhaltsblocks. Sie müssen diesen Wert in der translationsRegister-Mutation senden; Shopify verifiziert so, welcher ursprüngliche Inhalt übersetzt wurde. Ohne digest schlägt die Mutation fehl.
Solange pageInfo.hasNextPage true zurückgibt, setzen Sie den Loop fort, indem Sie den Wert von endCursor an den after-Parameter übergeben. In Shops mit mehr als 100 Produkten ist Paginierung obligatorisch.
2. Inhalte an die DeepL API senden
Um Inhalte von Shopify an DeepL zu senden, wird eine HTTP-POST-Anfrage verwendet:
POST https://api-free.deepl.com/v2/translate
Authorization: DeepL-Auth-Key {API_KEY}
Content-Type: application/json
{
"text": ["Ürün başlığı", "<p>Ürün açıklaması <strong>kalın metin</strong></p>"],
"source_lang": "TR",
"target_lang": "DE",
"tag_handling": "html"
}Das Senden mehrerer Texte in einer einzigen Anfrage optimiert sowohl Ihr API-Kontingent als auch die Antwortzeit. DeepL akzeptiert maximal 50 Textblöcke pro Anfrage.
Beachten Sie Folgendes: Wenn das Feld body_html Shopify-spezifische {{ variable }} Liquid-Ausdrücke enthält, ersetzen Sie diese Ausdrücke vor dem Senden zur Übersetzung durch Platzhalter und fügen Sie sie nach Erhalt der Übersetzung wieder ein. Andernfalls würde DeepL diese Ausdrücke ebenfalls übersetzen und das Liquid wäre beschädigt.
3. Übersetzungen in Shopify speichern
Die `translationsRegister`-Mutation schreibt die von DeepL zurückgegebenen Übersetzungen in Shopify:
mutation RegisterTranslations($resourceId: ID!, $translations: [TranslationInput!]!) {
translationsRegister(resourceId: $resourceId, translations: $translations) {
userErrors {
field
message
}
translations {
key
value
locale
}
}
}Variablen:
{
"resourceId": "gid://shopify/Product/1234567890",
"translations": [
{
"key": "title",
"value": "Produkttitel auf Deutsch",
"locale": "de",
"translatableContentDigest": "abc123..."
},
{
"key": "body_html",
"value": "<p>Produktbeschreibung auf Deutsch</p>",
"locale": "de",
"translatableContentDigest": "def456..."
}
]
}Überprüfen Sie das Feld `userErrors`. Wenn Sie den Fehler `BLANK_TRANSLATION_VALUE` erhalten, entfernen Sie das entsprechende Feld aus dem `translations`-Array, anstatt einen leeren String zu senden. Der Fehler `INVALID_DIGEST` weist darauf hin, dass der `translatableContentDigest` falsch ist; führen Sie die Abfrage erneut aus, um den aktuellen Digest zu erhalten.
4. Automatischer Übersetzungs-Workflow mit Webhooks
Anstatt manuell zu übersetzen, können Sie eine automatische Auslösung einrichten, wenn ein neues Produkt hinzugefügt wird. Leiten Sie den `products/create`-Webhook in Shopify an einen Endpunkt auf Ihrem eigenen Server weiter:
POST https://your-server.com/webhooks/product-createdDer Endpunkt verarbeitet den folgenden Workflow:
- `product.id` aus dem Webhook-Payload abrufen
- Übersetzbare Inhalte des Produkts mit der `translatableResources`-Abfrage abrufen
- An die DeepL API senden
- Mit `translationsRegister` in Shopify schreiben
- Den Vorgang protokollieren
Vergessen Sie nicht, Shopify-Webhooks zu validieren. Jeder Webhook-Anfrage-Header enthält den Wert `X-Shopify-Hmac-Sha256`; wenn Sie diesen Wert nicht mit Ihrem eigenen Secret Key mittels HMAC-SHA256 berechnen und vergleichen, bleiben Sie anfällig für gefälschte Anfragen.
Tipp: Der Übersetzungsprozess sollte asynchron ausgeführt werden. Wenn die Webhook-Antwort länger als 5 Sekunden dauert, initiiert Shopify einen erneuten Versuch, und dasselbe Produkt wird mehrfach übersetzt. Geben Sie sofort nach Erhalt des Webhooks 200 OK zurück und überlassen Sie die eigentliche Arbeit einer Job-Warteschlange (z. B. Redis + Bull oder AWS SQS).
App vs. API: Vergleich von Weglot, Langify und DeepL
Obwohl die Shopify-Übersetzungs-Apps auf dem Markt die Arbeit mit einem Klick erledigen zu scheinen, treten bei der Skalierung Kosten- und Kontrollprobleme auf.
Die Preisgestaltung von Weglot skaliert nicht nach Wortzahl, sondern nach Seitenaufrufen. Für einen Shop mit 200.000 Seitenaufrufen pro Monat kostet der Business-Plan jährlich 2.388 $. Für denselben Shop sind DeepL Pro + einmalige Entwicklungskosten im ersten Jahr in der Regel niedriger und ab dem zweiten Jahr deutlich vorteilhafter.
Apps wie Weglot und Langify funktionieren, indem sie JavaScript in den Theme-Code injizieren. Diese Methode wirkt sich negativ auf die Core Web Vitals-Metriken aus, insbesondere auf LCP und TBT. Die DeepL API-Integration hingegen schreibt die Übersetzungen direkt in die Shopify-Datenbank; der Theme-Code bleibt unberührt.
Hreflang und mehrsprachiges SEO: Was Shopify automatisch macht und wo es Defizite gibt
Shopify fügt für aktive Locales automatisch <link rel="alternate" hreflang="..."> Tags in den <head>-Bereich ein. Wenn in Ihrem Shop das Locale "de" aktiv ist, werden deutsche Produktseiten unter der URL https://sizinmagazaniz.com/de/products/urun-adi veröffentlicht, und auf der türkischen Seite erscheint automatisch der hreflang="de"-Tag.
Automatisch von Shopify hinzugefügte Hreflang-Tags
Die Unterverzeichnisstruktur (/de/, /fr/) ist das Standardverhalten von Shopify und die von Google empfohlene Struktur. Für eine Subdomain (de.example.com) oder eine separate Domain (example.de) ist eine externe DNS-Konfiguration und eine benutzerdefinierte Domainzuweisung in Shopify Markets erforderlich.
Übersetzung von Meta-Title und Meta-Description
Die Shopify Translations API unterstützt auch die Felder meta_title und meta_description. Wenn Sie diese Felder nicht übersetzen, erscheinen auf der deutschen Seite türkische Meta-Tags; Google kategorisiert die Seite in diesem Fall falsch in der Zielsprache.
In der Liste translatableContent erscheinen diese Felder als key: "meta_title" und key: "meta_description". Fügen Sie sie in dieselbe translationsRegister-Mutation wie die Produktübersetzung ein.
Handle-Übersetzung und SEO-Warnung
Es ist möglich, Produkt-Handles (URL-Slugs) zu übersetzen, aber Vorsicht ist geboten. Wenn der Handle geändert wird, führt die alte URL zu einem 404-Fehler. Shopify erstellt keine automatischen Weiterleitungen. Es ist SEO-sicherer, die Handles im Original zu belassen, anstatt sie zu ändern. Wenn Sie aussagekräftige URLs in der Zielsprache wünschen, planen Sie die Erstellung von Weiterleitungen als separaten Schritt ein.
Für einen umfassenden technischen Leitfaden zum Thema Shopify SEO Shopify SEO-Optimierung lesen Sie unseren Inhalt.
3 kritische Beobachtungen aus der Praxis von Nodus Works
Beobachtung 1: Liquid-Ausdrücke im Feld body_html lassen Integrationen abstürzen
Shopify-Theme-Entwickler betten manchmal {% if %}-Blöcke oder {{ metafield }}-Ausdrücke in Produktbeschreibungen ein. Wenn dieser Inhalt direkt an DeepL gesendet wird, ergeben sich zwei Möglichkeiten: Entweder wird der Liquid-Ausdruck übersetzt und beschädigt, oder DeepL ignoriert den Ausdruck und übersetzt den umgebenden Text, und der Eintrag erscheint fehlerfrei. Wenn Shopify diese Übersetzung jedoch rendert, erscheint die Seite leer oder fehlerhaft, da der Liquid-Code fehlerhaft verarbeitet wurde. Richten Sie vor dem Senden ein Platzhaltersystem mit Regex für {{ }}- und {% }-Blöcke ein.
Beobachtung 2: Die vollständige Übersetzung eines Shops mit 500 Produkten überschreitet das kostenlose Limit nicht
In einem typischen türkischen E-Commerce-Shop mit 500 Produkten haben wir eine durchschnittliche Titelgröße von 60 Zeichen, eine Beschreibung von 800 Zeichen und Metafelder von 200 Zeichen gemessen. Das sind durchschnittlich 1.060 Zeichen pro Produkt, insgesamt 530.000 Zeichen. Diese Zahl überschreitet das monatliche kostenlose Limit von DeepL von 500.000 Zeichen nur geringfügig. Wenn Sammlungs-, Seiten- und Blog-Inhalte ausgeschlossen werden, passt der Großteil in das kostenlose Limit. Werden Seiten- und Blog-Inhalte einbezogen, kann ein Pro-Plan erforderlich sein.
Beobachtung 3: Vierzig Prozent der App-Nutzer glauben, dass Übersetzungen „verschwunden“ sind; tatsächlich wurde das Gebietsschema gelöscht.
Ein häufiges Szenario, das wir in Shops mit Weglot oder Langify beobachten: Ein Entwickler entfernt unbeabsichtigt das Gebietsschema aus den Markets, während er ein Theme aktualisiert oder eine Einstellung im Shopify-Backend ändert. Die App speichert die Übersetzungen in ihrer eigenen Datenbank, aber Shopify zeigt dieses Gebietsschema nicht mehr an. Der Benutzer gerät in Panik und öffnet ein Support-Ticket. Bei der DeepL API-Integration werden Übersetzungen im eigenen Übersetzungssystem von Shopify gespeichert; wenn das Gebietsschema gelöscht und erneut hinzugefügt wird, kehren die Inhalte zurück.
FAQ
Ist es zwingend erforderlich, Softwarekenntnisse zu besitzen, um die DeepL API in Shopify zu nutzen?
Grundlegende JavaScript- oder Python-Kenntnisse sind ausreichend. Die Shopify GraphQL API funktioniert über Standard-HTTP-Anfragen und erfordert kein spezielles SDK. Für Webhook-basierte Automatisierung müssen Sie jedoch einen Server (Node.js, Python Flask/FastAPI oder eine Serverless-Funktion) einrichten können. Wenn Sie keine technische Infrastruktur aufbauen möchten, ist die Zusammenarbeit mit einer Shopify-Agentur, die diese Integration für Sie einrichten kann, langfristig wirtschaftlicher als die Kosten der Anwendung selbst.
Ist die Shopify Translations API kostenlos?
Ja, die Shopify Translations API ist in allen Tarifen kostenlos. Der kostenlose Tarif der DeepL API deckt Übersetzungen von bis zu 500.000 Zeichen pro Monat ab. Sie müssen nur dann bezahlen, wenn Sie das kostenlose Limit von DeepL überschreiten; in diesem Fall beginnt der DeepL Pro-Tarif bei etwa 25 US-Dollar pro Monat.
Wie viele Sprachen unterstützt die translationsRegister Mutation?
Shopify unterstützt über die Translations API bis zu 20 Locales. Die vollständige Liste der unterstützten Sprachen kann über die supportedLocales Query von Shopify abgerufen werden. Es sind über 60 Sprachen verfügbar, darunter Türkisch (tr), Deutsch (de), Englisch (en), Arabisch (ar), Französisch (fr).
Können Übersetzungen manuell im Shopify Admin bearbeitet werden?
Ja. Mit translationsRegister registrierte Übersetzungen erscheinen im Shopify Admin unter Settings > Languages und können dort bearbeitet werden. Dies kann genutzt werden, um die automatischen Übersetzungen von DeepL manuell zu verbessern. Vorgenommene Änderungen werden beim nächsten Webhook-Trigger nicht gelöscht; wenn die API jedoch aufgrund einer Digest-Änderung bei der Produktaktualisierung neu schreibt, wird Ihre Bearbeitung überschrieben. Um dies zu verhindern, fügen Sie dem Webhook-Flow eine Prüfung "bereits übersetzt und bearbeitet?" hinzu.
Unterstützt die DeepL API Türkisch?
Ja. DeepL unterstützt Türkisch seit 2022 sowohl als Quell- als auch als Zielsprache. Die Übersetzungsqualität vom Türkischen ins Englische und Deutsche ist, insbesondere bei E-Commerce-Texten, messbar höher im Vergleich zu Google Translate. DeepLs 2023 Qualitätsvergleichsbericht, dokumentiert eine Benutzerpräferenzrate von 85 % für türkische Sprachpaare.
Funktioniert diese Integration ohne Shopify Markets?
Nein. Der Locale-Parameter der translationsRegister Mutation muss einem aktiven Locale in Shopify Markets entsprechen. Eine Registrierung ohne aktiviertes Locale führt zu einem LOCALE_NOT_ENABLED-Fehler. Um Shopify Markets zu aktivieren, gehen Sie im Admin-Bereich zu Settings > Markets > Add market .
Wie lange dauert es, einen Shopify-Shop mit DeepL zu übersetzen?
Für einen Shop mit 500 Produkten dauert die Ersteinrichtung 1-3 Tage: einschließlich der Erstellung einer Custom App, dem Schreiben und Testen der API-Integration. Der Übersetzungsprozess selbst variiert je nach Geschwindigkeit von DeepL; für 500 Produkte ist das massenhafte Abrufen und Schreiben in der Regel innerhalb von 10-30 Minuten abgeschlossen. Sobald die Webhook-basierte Automatisierung eingerichtet ist, erfolgt die Übersetzung bei jedem neuen Produkt automatisch innerhalb von 1-2 Minuten.
Ist es besser, in Shopify die API anstelle einer Übersetzungs-App zu verwenden?
Wenn Sie über die technische Infrastruktur verfügen und einen mehrsprachigen Shop länger als 2 Jahre betreiben möchten, ist der API-Ansatz vorteilhafter. Die Verwendung einer App minimiert die Einrichtungszeit, aber die Kosten steigen mit der Skalierung, die Seitenladezeit wird durch JavaScript-Lasten beeinträchtigt und es entsteht eine Anbieterabhängigkeit. Nach einer einmaligen Einrichtung nähern sich die Kosten nahezu Null; diese Investition amortisiert sich innerhalb von 6 Monaten.
Welche Inhalte können mit der Shopify Translations API übersetzt werden?
Produkttitel, Beschreibungen, Kollektionsseiten, Blogbeiträge, statische Seiten, Navigationslinks, Produktvariantenoptionen, Metafelder und Theme-Textstrings können übersetzt werden. Produktbilder, Preise und Lagerbestandsinformationen sind vom Übersetzungsbereich ausgeschlossen.
Fazit
Die Kombination der Shopify Translations API mit der DeepL API schafft eine vollständig kontrollierte, kostengünstige und performanceneutrale Übersetzungs-Infrastruktur für Ihren Shop. Anstelle der monatlichen Fixkosten von Apps wie Weglot oder Langify zahlen Sie nur pro tatsächlich genutztem Zeichen; die Übersetzungen werden nativ im Shopify-eigenen System gespeichert.
Kritischer technischer Hinweis: Verwalten Sie den translatableContentDigest korrekt, schützen Sie Liquid-Ausdrücke in body_html mit Platzhaltern und konfigurieren Sie die Webhook-Antwort asynchron.
Um diese Integration in Ihrem Shopify-Shop einzurichten oder Ihre bestehende Übersetzungs-Infrastruktur neu zu konfigurieren, Shopify Integrationslösungen besuchen Sie unsere Seite oder kontaktieren Sie uns direkt.
Für diejenigen, die gleichzeitig auch Versand- und Zahlungsintegrationen konfigurieren möchten, Shopify ERP-Integration deckt unser Leitfaden die entsprechende technische Infrastruktur ab.
