Tłumaczenia szablonów

Szablon możesz wysyłać w kilku językach. Ma jeden język domyślny i do 29 wersji językowych (tłumaczeń). ID szablonu jest takie samo we wszystkich językach, więc twój kod dodaje tylko język, którego potrzebuje – na przykład locale: 'de' – a Frontmail wybiera właściwą wersję.

Nie jesteś ograniczony do ośmiu języków panelu: możesz użyć dowolnego języka zapisanego znacznikiem BCP 47, np. hu, nl albo pt-BR.

Co się tłumaczy, a co jest wspólne

Każda wersja językowa ma własne:

Temat,
treść HTML,
Wersję tekstową (generowaną automatycznie z HTML tłumaczenia albo pisaną ręcznie),
Nazwę nadawcy – opcjonalnie; jeśli zostawisz ją pustą, zostanie użyta nazwa nadawcy z języka domyślnego.

Cała reszta jest ustawiana raz, w języku domyślnym, i wspólna dla wszystkich języków: odbiorcy (Do, CC, BCC, Reply-To), E-mail nadawcy, parametry, Wstawiaj CSS inline przy zapisie, usługa, ustawienia ochrony, załączniki, automatyczna odpowiedź i zbieranie kontaktów.

To celowe: zasady bezpieczeństwa szablonu – dynamiczni odbiorcy i blokada treści, stałe pola nadawcy i walidacja parametrów – są w jednym miejscu, więc żadne tłumaczenie nie może ich osłabić. Wersja językowa może używać tylko parametrów, które istnieją w języku domyślnym.

Jak dodać język

Dodawanie i edycja tłumaczeń wymaga roli Właściciel, Administrator albo Programista.

Otwórz szablon. Nad kartami edytora jest pasek Języki z językiem domyślnym (oznaczonym jako Domyślny) i osobnym chipem dla każdej wersji językowej.
Kliknij Dodaj język.
W polu Język wybierz język z listy albo wpisz jego kod (np. pt-BR) i wybierz Użyj „pt-BR”.
W sekcji Zacznij od wybierz:
- Kopia języka domyślnego – tłumaczysz tekst samodzielnie,
- Tłumaczenie maszynowe – tłumaczy własny klucz dostawcy twojej organizacji (zobacz Tłumaczenie maszynowe); jeśli masz skonfigurowanych kilku dostawców, wybierz Usługę,
- Pusty – pusty temat i HTML.
Kliknij Dodaj język, przetłumacz lub sprawdź treść i kliknij Zapisz.

Dopóki nie zapiszesz nowego języka, jest on wersją roboczą (oznaczoną jako nowy). Tłumaczenie maszynowe korzysta tylko z zapisanego języka domyślnego – niezapisane zmiany w nim nie są uwzględniane.

Edycja tłumaczenia

Kliknij język na pasku Języki, żeby przełączyć na niego edytor. Edytor pokaże Edytujesz tłumaczenie: … i działa jak zwykle:

Treść – temat oraz karty HTML, Wizualny i Tekst edytują tłumaczenie. Przykładowe dane i podgląd są wspólne, a podgląd renderuje tłumaczenie dokładnie tak, jak zostanie wysłane. Parametry są tu tylko do odczytu (Parametry są wspólne dla wszystkich języków. Edytuj je w języku domyślnym.).
Ustawienia – do tłumaczenia należą tylko temat, Nazwa nadawcy i ustawienie wersji tekstowej; wspólne pola mają dopisek Wspólne dla wszystkich języków.
Kod i Wyślij test mają pole Język, więc możesz skopiować kod albo wysłać testowy e-mail w dowolnym języku.

Kontrole porównują też tłumaczenie z językiem domyślnym: parametr, który jest tylko w tłumaczeniu, to błąd (najpierw dodaj go do języka domyślnego), a parametr używany w języku domyślnym, którego brakuje w tłumaczeniu, to ostrzeżenie.

Plakietki Nieaktualny i Maszynowe

Nieaktualny – język domyślny został ponownie zapisany po zapisaniu tego tłumaczenia, więc tłumaczeniu może czegoś brakować. Wysyłka nadal działa. Zaktualizuj tłumaczenie i zapisz je, a jeśli wciąż pasuje – kliknij Oznacz jako aktualne.
Maszynowe – zapisana wersja pochodzi z tłumaczenia maszynowego. Sprawdź ją, zanim zaczniesz na niej polegać.

Gdy wybrane jest tłumaczenie, pasek oferuje też Przetłumacz ponownie (nowe tłumaczenie maszynowe zapisanego języka domyślnego; nic nie zostanie zapisane, dopóki nie klikniesz Zapisz) i Usuń język. Po usunięciu języka znikają też jego wersje, a e-maile, które o niego poproszą, są wysyłane w języku domyślnym.

Wersje i przywracanie

Każde zapisanie tłumaczenia tworzy jego nową wersję – każdy język ma własną numerację. Gdy wybrane jest tłumaczenie, karta Wersje pokazuje Wersje tłumaczenia … z kolumnami Na podstawie (wersja języka domyślnego, względem której tłumaczenie zapisano) i Pochodzenie (Ręczne albo Maszynowe). Wersje porównujesz i starszą Przywracasz tak samo jak w języku domyślnym.

Wiadomość zawsze zapamiętuje język i wersję tłumaczenia, z którą została wyrenderowana. E-maile czekające w kolejce wstrzymanych wiadomości są wysyłane z wersjami, które były bieżące w chwili ich przyjęcia.

Zmiana języka domyślnego

Język domyślny znajdziesz w Ustawienia → Ogólne → Język domyślny. Możesz wybrać dowolny język poza takim, który ma już wersję językową – najpierw ją usuń.

Wysyłka w wybranym języku

Język zawsze wybiera jawnie nadawca. Frontmail nie zgaduje go na podstawie przeglądarki (Accept-Language) – jeśli chcesz użyć języka odwiedzającego, przekaż go sam.

Jak wybierany jest język

Dla żądanego locale Frontmail używa:

brak locale → języka domyślnego,
dokładne dopasowanie (wielkość liter nie ma znaczenia) → tego języka,
ten sam język bazowy → de-AT dostaje de; pt dostaje wersję pt-…, np. pt-BR,
w pozostałych przypadkach → języka domyślnego.

Nieznany język nie jest błędem – locale to tylko preferencja. Odrzucany jest wyłącznie błędnie zapisany znacznik (np. "german!"), z błędem 400 invalid_body.

Odpowiedź mówi, który język został faktycznie użyty:

{ "message_id": "msg_…", "status": "queued", "status_token": "…", "locale": "de" }

REST API

Dodaj locale do POST /v1/send (i do każdej wiadomości w POST /v1/send-batch):

{
  "template_id": "tpl_01J9…",
  "template_params": { "name": "Jana" },
  "locale": "de"
}

POST /v1/send-form używa zarezerwowanego pola formularza fm_locale. Pole o nazwie locale pozostaje zwykłym parametrem szablonu, więc istniejące formularze działają dalej:

<select name="fm_locale">
  <option value="pl">Polski</option>
  <option value="de">Deutsch</option>
</select>

SDK

Każde SDK ma opcję locale i zwraca użyty język w result.locale.

Przeglądarka (@frontmail/browser) – sendForm wysyła go jako fm_locale; własne pole fm_locale w formularzu ma pierwszeństwo:

const result = await send('svc_01J9…', 'tpl_contact', { name: 'Jana' }, { locale: 'de' });
await sendForm('svc_01J9…', 'tpl_contact', '#contact', { locale: document.documentElement.lang });
console.log(result.locale); // 'de'

React (@frontmail/react) – prop locale komponentu <FrontmailForm> albo options.locale w send / sendForm. Vue i Svelte działają tak samo:

<FrontmailForm serviceId="svc_01J9…" templateId="tpl_contact" locale="de">…</FrontmailForm>

const { send } = useSendEmail('svc_01J9…', 'tpl_contact');
await send({ name: 'Jana' }, { locale: 'de' });

Node.js (@frontmail/node):

const { locale } = await frontmail.send({ templateId: 'tpl_order', params: { order_id: 'A-1042' }, locale: 'de' });
await frontmail.sendBatch([{ templateId: 'tpl_reminder', params: { name: 'Jana' }, locale: 'cs' }]);

Android / Kotlin (dev.frontmail:frontmail):

val result = frontmail.send(
    "tpl_contact",
    mapOf("name" to name),
    options = SendOptions(locale = Locale.getDefault().toLanguageTag()),
)
println(result.locale) // "de"

iOS / Swift (Frontmail dla Swift) – użyj Locale.preferredLanguages.first (np. de-AT); Locale.current.identifier zawiera _ i nie jest poprawnym znacznikiem:

let result = try await frontmail.send(
    templateID: "tpl_contact",
    params: ["name": "Jan"],
    options: SendOptions(locale: Locale.preferredLanguages.first)
)
print(result.locale ?? "default") // "de"

Flutter / Dart (frontmail) – użyj toLanguageTag() (np. de-AT); Locale.toString() używa _ i nie jest poprawnym znacznikiem:

final result = await frontmail.send(
  templateId: 'tpl_contact',
  params: {'name': 'Jan'},
  options: SendOptions(locale: Localizations.localeOf(context).toLanguageTag()),
);
print(result.locale ?? 'default'); // "de"

W React Native użyj send(params, { locale: 'de' }) z useSendEmail. npx frontmail types wypisuje języki każdego szablonu i generuje dla nich typ – zobacz Node.js.

Automatyczne odpowiedzi, ponowne wysyłki i EmailJS

Automatyczna odpowiedź podąża za językiem pierwotnej wiadomości: szablon automatycznej odpowiedzi wybiera dla tego języka własną wersję językową według tych samych zasad (a w razie potrzeby używa swojego języka domyślnego).
Wyślij ponownie w Historii wysyła wiadomość jeszcze raz w tym samym języku, z bieżącą wersją tłumaczenia. Jeśli ten język został w międzyczasie usunięty, używany jest język domyślny.
Ścieżki zgodne z EmailJS (/api/v1.0/email/…) i @frontmail/emailjs-compat zawsze wysyłają język domyślny.

Formatowanie zgodne z językiem e-maila

E-mail jest renderowany w języku, w którym jest wysyłany. formatDate, formatNumber i formatMoney formatują daty, liczby i kwoty dla tego języka (wersja niemiecka wypisze 1. Oktober 2026 i 49,00 €). Stopka Wysłano przez Frontmail w planie Free jest w języku e-maila, jeśli to jeden z ośmiu języków panelu, w przeciwnym razie po angielsku.

Tłumaczenie maszynowe

Frontmail może przetłumaczyć szablon za ciebie przez OpenAI, Anthropic, Google Gemini albo DeepL – z użyciem własnego klucza API twojej organizacji („bring your own key”). Frontmail nigdy nie tłumaczy na własny rachunek, a tłumaczenie maszynowe nie zużywa kredytów Frontmaila; za użycie rozlicza cię bezpośrednio dostawca.

Tłumaczenie maszynowe zawsze uruchamiasz ręcznie: działa tylko wtedy, gdy w oknie Dodaj język wybierzesz Tłumaczenie maszynowe albo klikniesz Przetłumacz ponownie, a wynikiem jest wersja robocza, którą sprawdzasz przed zapisaniem.

Jak skonfigurować klucz dostawcy

Klucze mogą dodawać i zmieniać tylko Właściciele i Administratorzy. Programiści widzą, którzy dostawcy są skonfigurowani (tylko do odczytu), i mogą ich używać do tłumaczenia.

Otwórz Ustawienia → Tłumaczenie maszynowe.
Przy wybranym dostawcy kliknij Dodaj klucz. Link Zdobądź klucz … otwiera stronę z kluczami dostawcy.
Wklej Klucz API. W OpenAI, Anthropic i Gemini możesz podać Model (opcjonalnie); zostaw puste, żeby użyć domyślnego modelu dostawcy. DeepL nie ma wyboru modelu.
Kliknij Zapisz klucz. Przed zapisaniem Frontmail sprawdza klucz małym zapytaniem do dostawcy.

Jeśli masz kilku dostawców, kliknij Ustaw jako domyślną, żeby wybrać, który będzie podpowiadany. Przy każdym skonfigurowanym dostawcy są przyciski Zastąp klucz i Usuń; usunięcie klucza nie rusza już zapisanych tłumaczeń.

Klucz jest przechowywany w postaci zaszyfrowanej i nigdy więcej nie jest pokazywany – panel wyświetla tylko jego cztery ostatnie znaki. Każda zmiana trafia do dziennika zdarzeń.

Co trafia do dostawcy

Tylko temat, HTML, wersja tekstowa i nazwa nadawcy zapisanego języka domyślnego – wersja tekstowa tylko wtedy, gdy jest pisana ręcznie (automatyczna jest generowana z przetłumaczonego HTML). Nic innego nie opuszcza Frontmaila: żadni odbiorcy, wartości parametrów, przykładowe dane, kontakty ani historia wiadomości. Żądanie idzie bezpośrednio z serwerów Frontmaila do oficjalnego API dostawcy, a do treści mają zastosowanie warunki tego dostawcy.

Jak sprawdzany jest wynik

Frontmail prosi dostawcę, żeby nie zmieniał wyrażeń Handlebars ({{name}}, {{#if …}}), znaczników i atrybutów HTML, linków ani adresów e-mail, a potem to weryfikuje: tłumaczenie musi zawierać dokładnie te same wyrażenia Handlebars oraz te same adresy linków i obrazków co źródło. Jeśli tak nie jest, wynik zostaje odrzucony z komunikatem Tłumaczenie maszynowe zmieniło parametry, linki lub strukturę HTML, więc nie zostało użyte. (translation_invalid) – spróbuj ponownie albo użyj innego dostawcy. Nic nie jest zapisywane częściowo.

Inne błędy: translation_not_configured (brak skonfigurowanego klucza), translation_provider_auth (dostawca odrzucił klucz) i translation_provider_error (dostawca zawiódł – spróbuj później).

Limity i koszty

30 tłumaczeń maszynowych na godzinę na organizację.
60 000 znaków treści źródłowej na jedno tłumaczenie; dłuższe szablony dostają payload_too_large.
Tłumaczenie musi się zakończyć w ciągu 60 sekund.
Koszty nalicza dostawca na konto, do którego należy klucz. Tłumaczenie nie zużywa kredytów Frontmaila, a wysyłka przetłumaczonego e-maila kosztuje tyle samo co każda inna – jeden kredyt.

Limity

30 języków na szablon – język domyślny i 29 wersji językowych.
Wersja językowa ma te same limity rozmiaru co treść samego szablonu.
Znacznik języka może mieć najwyżej 35 znaków.

Eksport i import

Eksportuj (.json) obejmuje wszystkie wersje językowe, a Importuj tworzy je ponownie w nowym szablonie. Starsze pliki eksportu bez wersji językowych importują się tak jak wcześniej.