Skip to main content
Translations help you localize notifications dynamically based on your user’s locale.
Instead of maintaining multiple templates per language, you can manage a single template and multiple translation files.
One template + multiple translation files = localized notifications for all your users.

​
How translations work

SuprSend automatically handles localization while sending notifications — no extra code required.

​
Steps to Enable Translations

  1. Upload translation files from the dashboard, via CLI, or API.
    Each file is a JSON containing key-value pairs consistent across locales.
  2. Set user locale in SDK using set_locale() or via the $locale property in create/update user API.
  3. Use translation keys inside templates:
    • Handlebars: {{t "key_name"}}
    • JSONNET: t("key_name")
  4. At the time of workflow execution, SuprSend looks for key_name in the user’s locale file and if not found, applies below fallback logic.

​
Fallback Logic

If either the locale file or key inside the locale file is missing, SuprSend searches in this order:
  1. Exact locale match — e.g., es-MX.json
  2. General language file — e.g., es.json
  3. Default language fallback — e.g., en.json
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.

​
Basic usage

Translations are JSON objects that define the localized text for your app messages in different locales. Let’s say you have a task management app and you want to notify users when a new task is created or completed — localized for English and French users. 
{
"TaskCreated": "A new task has been created: {{task_name}}",
"TaskCompleted": "Task {{task_name}} has been completed successfully!"
}


{
"task_created": "Une nouvelle tâche a été créée : {{task_name}}",
"task_completed": "La tâche {{task_name}} a été complétée avec succès !"
}
Once you have the files uploaded for en and fr locales, you can reference it in your templates using the t tag: 
{{t "task_created" task_name=task.name}} 
{{t "task_completed" task_name=task.name}}

​
Managing translation files

You can manage translation files from developers -> translations on the SuprSend dashboard, via API and CLI.

​
Flow

All translation changes, including delete, is version controlled and needs to be committed to make them live.

​
Directory structure

There are two ways to organize translation files:
  1. By locale code — one file per language, e.g. en.json, fr.json
  2. By namespace + locale code — group translations by feature or module within the same language, e.g. auth.en.json, tasks.fr.json. This comes in handy when you have different teams managing their translations or can have same key across different features or modules.
All files for a locale goes into a single directory. 
translations/
├── en/                  # English (base language)
│   ├── en.json         # General translations
│   └── auth.en.json    # namespaced translations
└── en-GB/              
    ├── en-GB.json      
    └── orders.en-GB.json

​
Add locale files

1

Upload file

Go to Developers → Translations section. Click on +New File button and upload locale files. Locale file naming convention:
  • {locale_code}.json: example: en.json, es-MX.json
  • {namespace}.{locale_code}.json: example: auth.en.json, orders.es-MX.json Upload Translation File
File uploads with wrong name would throw error on upload. Make sure to edit the name before upload.
2

Save Changes

Click Next to save. Files are saved as a draft version until committed.Upload translation file
3

Commit changes

Click Commit Changes to make translations live. Add a short description of your update for later reference. You can also skip this step and commit later.Commit translations

​
Update existing files

Download, edit locally, and re-upload updated translation files.
1

Download file

Click Download to save the translation file locally for editing.Download translation file
2

Edit, upload and commit

Make your edits to the downloaded JSON file, then click + New File and upload the edited file to replace the existing file. Finally, click Commit to make your translation changes live.

​
Delete files

Remove locale files that are no longer needed.
1

Delete file

Find the translation file you want to remove, and click Delete. This will mark the file for deletion in the draft version.Delete translation file
2

Commit deletion

Click Commit to make deletion live. The deletion will only take place after you commit.Commit translations

​
Version history and rollback

SuprSend uses git-like versioning for locale file changes. Every commit creates a new version that you can view, download, or roll back to.
  • View version history
    Click Version History to see all previous versions. You can download and view older files, and check the status column to see what changed compared to the previous version.
  • Rollback to an older version
    Inside version history tab, select the version you want to restore and click Rollback version.     Rollback translation

​
Using translations in templates

You can use translations in your templates using the t tag. Anything inside the t tag will be replaced with the translation for the key.

​
Simple, Nested and Namespaced keys

{{t "key_name"}}
{{t "feature:key_name"}} // for namespaced locale files
{{t "nested_key.sub_key"}} // for nested keys

​
Pluralization

Translations support plural forms using the keys zero, one, and other. When you pass a count variable, SuprSend automatically picks the correct form. If count is missing or null, the zero form is used by default. translation file:
en.json
{
  "tasks": {
    "zero": "You have no tasks",
    "one": "You have 1 task",
    "other": "You have {{count}} tasks"
  }
}
Rules:
  • count = 0 → uses zero form → "No items"
  • count = 1 → uses one form → "1 item"
  • count ≥ 2 → uses other form → "5 items"
template: 
{{t "tasks" count=$batched_events_count}}

​
Interpolation

If your translation includes variables, you can dynamically replace them with values from your template or workflow data like this: translation file:
en.json
{
  "greeting": "Hello, {{name}}!"
}
template: 
{{t "greeting" name=$recipient.name}}
Rendered content:
  • “Hello, John!” when $recipient.name is “John”

​
Combining with Handlebars helpers

Here, are some examples of how you can combine translations with other Handlebars helpers.
  1. Default value
{{default (t "name") "Guest"}}
  1. Conditional rendering
{{#if user.is_premium}}
{{t "premium_plan.details"}}
{{else}}
{{t "standard_plan.detail"}}
{{/if}}
  1. Looping
{{#each $batched_events}}
{{t "item_name"}}
{{/each}}

​
Automate translation with CLI and APIs

You can manage your translations files programmatically using:

​
Supported locales

SuprSend supports standard ISO locale codes following the language-COUNTRY format. Here’s the complete list of supported locales:
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
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.

​
Best practices

  • Keep keys short: auth:login > authentication_login_button_text
  • Always define plural forms wherever needed: zero, one, other for consistent behavior
  • Maintain en.json as the base language
  • Use translation keys everywhere — avoid raw text in templates
  • Whenever you’re adding new variables and updating translation files, make sure you update it across locales.

​
Troubleshooting

Even with proper setup, issues may be encountered. Here are common problems and their solutions:
Possible causes:
  • Latest translation files are not committed
  • User locale not set
  • Key missing in translation files
Refresh the page and load preview again. If you were already on the template page and translation files got updated, you may need to reload the page to see the latest changes.
Check if the format of variable name is correct in the locale file. It should be added as {{variable_name}} in the translation file.