Skip to main content
Translations localize the notifications you send with SuprSend. Instead of maintaining separate templates for each language, you can create a single template with translation keys that are automatically replaced with the appropriate language content based on the user’s locale setting.
Key concept: One template + multiple translation files = localized notifications for all your users.

​
How translations work

SuprSend handles localization behind the scenes. When a user receives a notification, it:
StepProcessHow it worksExample
1Detect user localeIdentifies from user profilees_MX
2Find best translation fileUses smart fallback logices-MX.json → es.json → en.json
3Replace keysSubstitutes with translated content{{t "welcome"}} → ¡Bienvenido!
4Send localized notificationDelivers in user’s preferred languageDelivered in Spanish (Mexico)
All this happens automatically — no extra code on your end. Translation files must follow this structure for SuprSend’s system to work correctly.

​
Translation directory structure

Translation files must be organized by locale codes: 
translations/
├── en/                  # English (base language)
│   ├── en.json         # General translations
│   └── auth.en.json    # Authentication-specific translations
└── en-GB/              # English (Great Britain)
    ├── en-GB.json      # General translations
    └── orders.en-GB.json # Order management translations
Naming convention: SuprSend supports both underscore (en_GB) and hyphen (en-GB) formats. Internally, both map to the same locale.
  • Language only
  • Language + Region
  • Namespaced files
Format: {language}.jsonContains translations for a specific language without regional variations.en.json (English)

​
Fallback logic

SuprSend automatically selects the best available translation for each user based on their locale. If a translation is missing, the system uses an intelligent fallback chain to ensure the notification is still localized. Fallback order:
  1. Exact locale match → es-MX.json (Spanish – Mexico)
  2. Language-only fallback → es.json (Spanish – General)
  3. Default fallback → en.json (Base language)
Best practice: Always maintain an en.json file as the base language. It ensures your system always has a fallback even if locale-specific keys are missing.

​
Translation key types

Translation keys can be organized using two main approaches:
  • Normal keys
  • Namespaced keys
Simple key-value pairs:
{
  "welcome": "Welcome!",
  "goodbye": "See you later!"
}

{{t "welcome"}}           <!-- Normal key -->
Benefits:
  • Simple and straightforward - Easy to understand and implement
  • Quick to set up - No need to plan namespaces upfront
  • Perfect for small projects - Ideal when you have limited translation keys
  • Direct access - Shorter syntax in templates
Potential conflict example:
{
  "title": "Welcome to our app",     // Auth page title
  "title": "Order confirmation"      // Order page title - CONFLICT!
}

​
Get started

Implementing translations in SuprSend requires three steps:
1

Upload translation files

Navigate to Dashboard → Developers → Translations and upload JSON files.Upload translation files interfaceCommit changes to make translations live. Learn more about managing translation files.
2

Set user locale

Set the user’s locale via API using the $locale parameter. The locale determines which translation file SuprSend will use for that user’s notifications. Use standard ISO locale codes like en_US, es_ES, fr_FR, etc.
3

Use in templates

Add translation keys to templates using the {{t}} tag:
Subject: {{t "greeting"}}
Body: {{t "welcome_message"}}, {{user.first_name}}!
Preview your translations:
  1. Open template editor and add {{t}} tags
  2. Click Preview (top right corner)
  3. Select different locales from the dropdown
  4. Verify output matches expectations Language dropdown for previewing translations
🎉 Notifications will now automatically display in each user’s preferred language.

​
Using translations in templates

The {{t}} tag is the primary tool for adding translations to templates. It replaces translation keys with localized content based on the user’s locale:
  • Simple translations
  • Namespaced translations
  • With variables
Basic key replacement - Direct translation key lookup without additional parameters.
{{t "welcome"}}        <!-- Outputs: "Welcome!" -->
{{t "goodbye"}}        <!-- Outputs: "See you later!" -->

​
Interpolation with variables

Translations can be made dynamic by injecting data from the application. Variables are passed as parameters and interpolated into the translation strings: 
{{t "greeting" name=user.first_name}}
{{t "order_confirmation" order_id=order.id customer=user.name}}
Translation file structure: 
{
  "greeting": "Hello, {{name}}!",
  "order_confirmation": "Hi {{customer}}, your order #{{order_id}} is confirmed!"
}

​
Pluralization

SuprSend supports plural forms automatically based on the count variable: 
{{t "items_count" count=cart.items.length}}
Translation file: 
{
  "items_count": {
    "zero": "No items",
    "one": "1 item",
    "other": "{{count}} items"
  }
}
Rule logic:
  • count=0 → zero
  • count=1 → one
  • count≥2 → other
The count variable is built-in. Always define zero, one, and other forms for consistent behavior across locales. This logic adapts automatically based on locale rules.

​
Combining translation with other helpers

The {{t}} tag can be combined with other Handlebars helpers to create more dynamic content:
  • Uppercase
  • Default values
  • Conditional content (if)
  • Loops with translations (each)
  • Email merge tags
Text transformation - Applies uppercase formatting to translated text.
{{t "welcome" | uppercase}}        <!-- "WELCOME!" -->

​
JSONNET support

JSONNET is useful when translation behavior depends on dynamic logic — for instance, tailoring messages based on subscription tier or user status. For advanced conditional logic beyond simple Handlebars helpers, use JSONNET expressions directly in your templates: In template: 
{{t "welcome_message" is_vip=user.is_premium tier=user.subscription_tier}}
In translation file (simple): 
{
  "welcome_message": "Welcome, {{tier}} member!"
}
For complex logic, use JSONNET in templates: 
local message = if user.is_premium then
  "Welcome, VIP member!"
else
  "Welcome!";

{
  subject: message,
  body: suprsend.t("welcome_body", {name: user.name})
}
JSONNET is useful for complex business logic. For most cases, simple variable interpolation and Handlebars helpers are sufficient.

​
Single template architecture

SuprSend uses a single template architecture with translation keys, eliminating the need for separate templates per language:
  • Multi-template approach
  • Single template approach
templates/
├── welcome_en.html
├── welcome_es.html
├── welcome_fr.html
└── welcome_de.html
Implementation: 
<div class="welcome-card">
  <h1>{{t "welcome_title"}}</h1>
  <p>{{t "welcome_message" name=user.first_name}}</p>
  <button>{{t "get_started"}}</button>
</div>
Benefits:
  • Simplifies updates - Change styling once, applies to all locales
  • Ensures styling consistency - No risk of layout differences between languages
  • Reduces maintenance overhead - Single template to maintain instead of multiple
This architecture reduces template maintenance overhead and ensures consistent styling across locales.

​
Managing translation files

  • 📋 Workflow
  • 🔄 Version control
Translation file workflow:
  1. Add translated files to the dashboard
  2. Commit changes to make translations live
  3. Delete translations by removing files and publishing changes
SuprSend automatically maintains version control for all translation files, tracking every change with timestamps and author information.
To delete a translation, you’ll need to publish the changes after removing the files.

​
Automating translation with CLI

Manage your translations programmatically using SuprSend’s Command Line Interface. Pull, push, and sync translation files with your local environment. For detailed CLI commands and workflows, see our CLI translations documentation.

​
Translation Management APIs

Programmatically manage translations using SuprSend’s Management APIs. Upload, delete, and manage translation files via API. For complete API reference and examples, see our Management API translations documentation.

​
Best practices

  • 🔑 Keep keys short**: auth:login > authentication_login_button_text
  • 🔢 Always define plural forms**: zero, one, other for consistent behavior
  • 📄 Maintain en.json** as your canonical source
  • 🏷️ Use translation keys everywhere** — avoid raw text in templates
  • 🏢 Don’t translate brand names — keep them consistent across locales

​
Supported locales

SuprSend supports standard ISO locale codes following the language_COUNTRY format:
Locale CodeLanguageCountry/Region
af_ZAAfrikaansSouth Africa
ar_AEArabicUnited Arab Emirates
ar_SAArabicSaudi Arabia
ar_EGArabicEgypt
az_AZAzerbaijaniAzerbaijan
be_BYBelarusianBelarus
bg_BGBulgarianBulgaria
bn_BDBengaliBangladesh
bs_BABosnianBosnia and Herzegovina
ca_ESCatalanSpain
cs_CZCzechCzech Republic
cy_GBWelshUnited Kingdom
da_DKDanishDenmark
de_ATGermanAustria
de_CHGermanSwitzerland
de_DEGermanGermany
el_GRGreekGreece
en_AUEnglishAustralia
en_CAEnglishCanada
en_GBEnglishUnited Kingdom
en_IEEnglishIreland
en_INEnglishIndia
en_NZEnglishNew Zealand
en_USEnglishUnited States
en_ZAEnglishSouth Africa
es_ARSpanishArgentina
es_CLSpanishChile
es_COSpanishColombia
es_ESSpanishSpain
es_MXSpanishMexico
es_PESpanishPeru
es_VESpanishVenezuela
et_EEEstonianEstonia
eu_ESBasqueSpain
fa_IRPersianIran
fi_FIFinnishFinland
fr_BEFrenchBelgium
fr_CAFrenchCanada
fr_CHFrenchSwitzerland
fr_FRFrenchFrance
gl_ESGalicianSpain
gu_INGujaratiIndia
he_ILHebrewIsrael
hi_INHindiIndia
hr_HRCroatianCroatia
hu_HUHungarianHungary
hy_AMArmenianArmenia
id_IDIndonesianIndonesia
is_ISIcelandicIceland
it_CHItalianSwitzerland
it_ITItalianItaly
ja_JPJapaneseJapan
ka_GEGeorgianGeorgia
kk_KZKazakhKazakhstan
km_KHKhmerCambodia
kn_INKannadaIndia
ko_KRKoreanSouth Korea
ky_KGKyrgyzKyrgyzstan
lo_LALaoLaos
lt_LTLithuanianLithuania
lv_LVLatvianLatvia
mk_MKMacedonianNorth Macedonia
ml_INMalayalamIndia
mn_MNMongolianMongolia
mr_INMarathiIndia
ms_MYMalayMalaysia
my_MMBurmeseMyanmar
ne_NPNepaliNepal
nl_BEDutchBelgium
nl_NLDutchNetherlands
no_NONorwegianNorway
pa_INPunjabiIndia
pl_PLPolishPoland
pt_BRPortugueseBrazil
pt_PTPortuguesePortugal
ro_MDRomanianMoldova
ro_RORomanianRomania
ru_RURussianRussia
si_LKSinhalaSri Lanka
sk_SKSlovakSlovakia
sl_SISlovenianSlovenia
sq_ALAlbanianAlbania
sr_RSSerbianSerbia
sv_SESwedishSweden
sw_KESwahiliKenya
ta_INTamilIndia
te_INTeluguIndia
th_THThaiThailand
tr_TRTurkishTurkey
uk_UAUkrainianUkraine
ur_PKUrduPakistan
uz_UZUzbekUzbekistan
vi_VNVietnameseVietnam
zh_CNChinese (Simplified)China
zh_HKChinese (Traditional)Hong Kong
zh_TWChinese (Traditional)Taiwan
zu_ZAZuluSouth Africa
Don’t see your locale? SuprSend supports all standard ISO 639-1 language codes and ISO 3166-1 alpha-2 country codes. Contact support if you need help with a specific locale.

​
Troubleshooting

Even with proper setup, issues may be encountered. Here are common problems and their solutions:
Possible causes:
  • Changes not committed
  • Invalid JSON format
  • User locale not set
  • Key missing in fallback files
Solutions:
  1. Check if changes are committed - Uncommitted translations won’t be used
  2. Verify file format - Ensure valid JSON syntax
  3. Check user locale - Confirm user profile has correct locale set
  4. Review fallback chain - Check if key exists in fallback files
Possible causes:
  • Incorrect locale format
  • Case-sensitive key names
  • Outdated version
Solutions:
  1. Verify locale format - Use en_US or en-US, not en-us
  2. Check key name - Keys are case-sensitive (greeting ≠ Greeting)
  3. Review version history - Ensure you’re on the latest version
Possible causes:
  • Incorrect syntax
  • Variable name mismatches
  • Wrong namespace format
Solutions:
  1. Syntax check - Ensure proper {{t "key"}} format
  2. Variable names - Check variable names match translation file
  3. Namespace format - Use namespace:key, not namespace.key
⌘I