Medusa i wielojęzyczność: jak działają tłumaczenia i co się psuje przy dużym katalogu

Przeniesienie kilku tysięcy kart produktu na drugi język rozbija się zwykle nie o język. Opis produktu to dane strukturalne w polu tekstowym: znaczniki, jednostki, wartości atrybutów i nazwy własne mają wrócić nietknięte, a zmienić ma się wyłącznie proza. Kiedy ta granica się zaciera, tłumaczenie czyta się świetnie, a mimo to psuje układ karty, filtry i wyszukiwanie na nowym rynku.

Na Medusie grunt przesunął się niedawno. Od wersji 2.12.3, wydanej 17 grudnia 2025, jest w rdzeniu moduł tłumaczeń, więc pytanie, gdzie trzymać drugą wersję językową, przestało być trudne. Bez odpowiedzi w platformie zostaje pytanie, czy wgrane tłumaczenie jest poprawne strukturalnie.

Dlaczego katalog jest trudniejszy niż tekst

Tłumaczenie artykułu to tłumaczenie zdań. Tłumaczenie katalogu to przepuszczenie przez jeden proces trzech różnych rodzajów treści, z których tylko jeden jest językiem.

• Proza: akapit marketingowy, opis zastosowania, wskazówki pielęgnacyjne. Jedyna warstwa, którą model ma prawo napisać po swojemu.
• Dane w przebraniu tekstu: wartości atrybutów, jednostki, wymiary, nazwy materiałów. Należą do słownika tłumaczonego raz i stosowanego wszędzie, a nie osobno przy każdym produkcie.
• Identyfikatory: marki, nazwy modeli, numery katalogowe, znaczniki HTML. Mają wrócić znak w znak, bo klient wpisuje je w wyszukiwarkę, a kanał sprzedaży dopasowuje po nich ofertę.

Te trzy warstwy przychodzą wymieszane w jednym polu. Opis, w którym po akapicie copy siedzi wypunktowana specyfikacja, niesie wszystkie naraz, plus HTML, który je od siebie oddziela. Model dostaje jeden ciąg znaków i traktuje go jak jedno zadanie.

Co Medusa daje dzisiaj, a czego nie

Najpierw fakty, sprawdzone 17 sierpnia 2026 w dokumentacji Medusy. Moduł tłumaczeń jest częścią rdzenia, ale nie działa domyślnie: dokumentacja wymaga wersji 2.12.3 lub nowszej, wpisu w tablicy modułów w medusa-config.ts, włączenia flagi funkcyjnej translation i migracji bazy.

Model danych jest celowo cienki. Rekord tłumaczenia wskazuje zasób trzema polami: nazwą tabeli, identyfikatorem zasobu i kodem języka w standardzie IETF BCP 47. Do tego niesie obiekt JSON z przetłumaczonymi polami, na przykład tytułem i opisem. Jeden zasób ma jedno tłumaczenie na język.

Sklep prosi o język parametrem locale w adresie albo nagłówkiem x-medusa-locale, przy czym parametr wygrywa, gdy są oba. Trasy sklepowe dostają to automatycznie, trasy własne wymagają dołożenia middleware applyLocale. Lista języków uzupełnia się sama przy pierwszym użyciu modułu, a obsługiwane wybiera się w ustawieniach sklepu.

Zakres jest produktowy. Tłumaczą się produkty, warianty, opcje, kategorie, kolekcje, tagi i typy, a poza tym regiony, metody dostawy, stawki podatku i grupy klientów. Dokumentacja mówi wprost, że obsługa wszystkich modułów handlowych przyjdzie w kolejnych wersjach, więc wszystko spoza tej listy jest dziś po Twojej stronie.

W panelu administracyjnym tłumaczenia edytuje się z poziomu konkretnego zasobu albo w edytorze zbiorczym per język, w ustawieniach. Można też wskazać, które zasoby i pola w ogóle podlegają tłumaczeniu. Wgranie całego katalogu to inna sprawa: dokumentacja pokazuje wywołanie serwisu modułu z poziomu workflow, więc import masowy piszesz sam.

Cztery lata zgłoszenia i osiem miesięcy odpowiedzi

Dla kontekstu, jak długo tego brakowało: zgłoszenie „Multi-language support" w repozytorium Medusy zostało otwarte 5 sierpnia 2022 i 17 sierpnia 2026 nadal jest otwarte, ze 111 komentarzami i odpowiedziami oraz 65 reakcjami kciuka w górę. Zapotrzebowanie było widoczne cztery lata.

Wniosek praktyczny jest inny, niż podpowiada odruch. Nie brzmi „Medusa nie ma wielojęzyczności", tylko: odpowiedź jest młoda i oznaczona jako eksperymentalna. Wersję sprawdź sam przed obietnicą wobec klienta. 13 sierpnia 2026 ukazała się 2.19.0, a moduł za flagą zmienia się szybciej niż jakikolwiek artykuł o nim.

Sześć rzeczy, które psują się przy masowym tłumaczeniu

Te awarie powtarzają się niezależnie od platformy i narzędzia, bo wynikają z kształtu danych, a nie z wyboru modelu. Każda ma kontrolę, którą wykona maszyna, i to jest tu najważniejsze: recenzent i tak zobaczy tylko próbkę.

• Znaczniki: tagi znikają, zagnieżdżają się inaczej albo się dublują, a wartości atrybutów w rodzaju tekstu alternatywnego po cichu stają się przetłumaczoną prozą.
• Nazwy własne: marki i nazwy modeli bywają tłumaczone, odmieniane albo „poprawiane", po czym klient nie znajduje ich w wyszukiwarce sklepu.
• Jednostki i formaty liczb: zmienia się separator dziesiętny, liczba bywa przeliczona bez pytania, a odstęp między wartością a jednostką raz jest, raz go nie ma.
• Atrybuty kontra opis: ta sama wartość atrybutu dostaje przy każdym produkcie trochę inne brzmienie, więc filtr rozpada się na warianty tego samego.
• Długość pól: przetłumaczone pole wychodzi poza limit kanału albo poza układ, w którym mieściła się wersja źródłowa.
• Rozjazd terminologii: trzecia partia używa innego słowa niż pierwsza, bo nic nie przeniosło decyzji między uruchomieniami.

Znaczniki: porównuj sekwencję tagów, nie tekst

Skuteczną barierą nie jest lepsze zdanie w prompcie. Jest nią porównanie wejścia i wyjścia na poziomie struktury: uporządkowana sekwencja tagów otwierających i zamykających wraz z atrybutami ma być identyczna, a różnić się mogą wyłącznie węzły tekstowe.

Taka kontrola jest tania w napisaniu i zerojedynkowa, więc jej miejsce jest w procesie jako bramka, nie w recenzji. Co nie przechodzi, wraca do ponowienia albo do człowieka i nie trafia do pola. Wersja ostrzejsza parsuje HTML, tłumaczy węzły tekstowe pojedynczo i składa dokument z powrotem, dzięki czemu znaczników nigdy nie ma w odpowiedzi modelu.

Nazwy własne: wyjmij je, zanim model je zobaczy

Lista „tego nie tłumaczymy" w prompcie pomaga i nie wytrzymuje skali. Wytrzymuje podmiana: każdą chronioną nazwę zastępujesz znacznikiem zastępczym przed wysyłką i przywracasz po powrocie. Kontrola robi się banalna, bo każdy znacznik, który wyszedł, ma wrócić dokładnie raz.

Ta sama sztuczka obejmuje numery katalogowe, rozmiary zapisane kodem i wszystko inne, co jest identyfikatorem, a nie słowem. Przy okazji zamienia awarię cichą w głośną, o co w całym tym ćwiczeniu chodzi. W polskim katalogu dochodzi jeszcze odmiana: nazwa modelu odmieniona przez przypadek to nadal zły identyfikator, choć brzmi naturalnie.

Jednostki i liczby to dane, nie język

Modelowi nie wolno przeliczać niczego. Przeliczenie między systemami jednostek jest regułą w danych, z tabelą per rynek, i albo uruchamia się świadomie, albo nie uruchamia wcale. Od kroku tłumaczenia oczekujesz tych samych tokenów liczbowych, w tej samej kolejności.

Formatowanie to osobna decyzja, podjęta raz na rynek: separator dziesiętny, separator tysięcy i odstęp między wartością a jednostką. Zastosowane regułą jest spójne w całym katalogu. Zostawione modelowi bywa spójne w obrębie partii i inne w następnej.

Recenzent widzi próbkę. Te sześć kontroli widzi cały katalog, dlatego idą pierwsze.

Glosariusz jest plikiem w procesie, nie dokumentem na dysku

Każdy projekt, który wypuszcza tysiące przetłumaczonych pól, kończy z tym samym artefaktem, jakkolwiek go nazwie: maszynowo czytelną listą decyzji, która jedzie z każdą partią. Pracują w niej trzy części.

• Nie tłumaczymy: marki, nazwy modeli, numery katalogowe, nazwy składników, które świadomie zostają w języku źródłowym. Z tej listy powstają znaczniki zastępcze.
• Brzmienia zatwierdzone: jedna forma docelowa na termin, łącznie z tymi niewygodnymi, gdzie słownik podaje trzy poprawne, a Twoja kategoria używa jednej.
• Słownik atrybutów: zamknięta lista wartości, przetłumaczona raz i nakładana jako dane, żeby kolor i materiał nie były tłumaczone od nowa przy każdym produkcie.

Pamięć tłumaczeń to ta sama myśl rozciągnięta w czasie. Bez niej czwarta partia nie wie, co ustaliła pierwsza, i katalog rozjeżdża się w sposób, którego nikt nie zauważy, dopóki klient nie zapyta, czym różnią się dwa identyczne produkty.

Ludzką połowę tej pętli, czyli kto recenzuje, według jakiego kryterium i jak poprawki wracają jako reguły, rozłożyliśmy osobno w tekście o tłumaczeniu katalogu z AI. Ten artykuł trzyma się połowy maszynowej, bo to jest ta część, którą platforma może wymusić.

Co sprawdzić, zanim cokolwiek pójdzie na produkcję

Cztery kontrole, w tej kolejności. Trzy pierwsze są automatyczne i obejmują całość. Czwarta jest ludzka i obejmuje próbkę, co ma sens dopiero wtedy, gdy trzy pierwsze są czyste.

• Walidacja struktury: zgodność tagów, znaczników zastępczych i tokenów liczbowych. Odrzucaj wiersz, nie partię, i trzymaj odrzucone na widoku.
• Raport pokrycia: zapytanie o tłumaczenia per język i per pole, zestawione z listą zasobów, które powinny je mieć. Przez mechanizm wartości zapasowej nie da się tego zrobić, oglądając sklep.
• Raport długości: każde przetłumaczone pole zmierzone wobec limitu miejsca, do którego jedzie, łącznie z układem karty i feedem kanału. Oznaczaj, nie przycinaj po cichu.
• Próbka ludzka: recenzent znający rynek docelowy czyta próbkę z każdej partii, dobraną z przewagą kategorii trudnych, nie łatwych.

Takie procesy budujemy w środku platformy, a nie obok niej, jako etap AI Automation w BEAM, więc glosariusz, walidatory i krok wgrywania mieszkają w tym samym repozytorium co sklep.

Kiedy nie warto tego automatyzować

Poniżej pewnej skali cały ten aparat kosztuje więcej niż praca, którą zastępuje. Kilkaset stabilnych produktów wchodzących na jeden rynek to zlecenie tłumaczeniowe z korektą, i dobry tłumacz zrobi je lepiej niż proces, bo proces trzeba najpierw zbudować, dostroić i utrzymywać.

Koszt stały jest realny: lista terminów, walidatory, krok wgrywania, pętla recenzji. Nasze prace w etapie AI Automation zaczynają się od 6 000 zł netto za workflow. To zakres do rozmowy o wycenie, a nie oferta, i uczciwe porównanie prowadzi się z jednorazowym kosztem ręcznego tłumaczenia Twojego katalogu, a nie z zerem.

Automatyzacja zaczyna się zwracać, gdy katalog żyje: nowe produkty co tydzień, opisy poprawiane przez kilka osób, drugi i trzeci rynek w planie. Wtedy koszt rozkłada się na wszystkie przyszłe partie, a nie na jedną. Jak wyceniamy takie prace, opisujemy w cenniku.

Drugi warunek zatrzymania nie ma nic wspólnego ze skalą. Jeśli nikt w firmie nie potrafi ocenić, czy wynik brzmi jak sklep z tamtego rynku, proces wyprodukuje płynny tekst, którego nie ma kto zaakceptować. Ile z wejścia na nowy rynek nie jest w ogóle językiem, zebraliśmy w checkliście wejścia na rynek niemiecki.

Nic z tego nie jest specyficzne dla Medusy, ale na Medusie jest to dziś najłatwiejsze do zrobienia porządnie, bo w rdzeniu jest wreszcie miejsce na tłumaczenia i API, które podaje je per język. Co budujemy wokół tego, opisujemy na stronie AI tłumaczenia katalogu. Stronę platformową pokrywają wdrożenia Medusa.js i platformy eCommerce.

Źródła

Wszystkie odnośniki sprawdzone 17 sierpnia 2026. Moduł jest oznaczony jako eksperymentalny i ukryty za flagą funkcyjną, więc przed wdrożeniem sprawdź stan dokumentacji dla swojej wersji.

• Medusa, dokumentacja modułu tłumaczeń: docs.medusajs.com/resources/commerce-modules/translation oraz sekcje o modelu danych i o warstwie sklepowej.
• Medusa, lokalizacja w trasach API: docs.medusajs.com/learn/fundamentals/api-routes/localization.
• Medusa, przewodnik panelu, ustawienia tłumaczeń: docs.medusajs.com/user-guide/settings/translations.
• Medusa, wydanie v2.12.3 z 17 grudnia 2025, w którym pojawiły się tłumaczenia: github.com/medusajs/medusa/releases/tag/v2.12.3.
• Medusa, zgłoszenie „Multi-language support" z 5 sierpnia 2022, nadal otwarte: github.com/medusajs/medusa/discussions/2003.