Translations

​

How translations work

1. Detect locale → Reads user’s $locale (set via API with $set_locale action or $locale parameter). Falls back to account default if unset.
2. Find translation file → Searches using fallback hierarchy:
   • Exact match: es_MX.json (for es_MX locale)
   • Language fallback: es.json
   • Default fallback: en.json
3. Replace keys → Replaces {{t "key_name"}} tags with translated values from the selected file. Interpolates variables like {{t "greeting" name=user.first_name}}.
4. Send notification → Delivers localized content to the user.

​

Translation directory structure

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

​

Fallback logic

1. First try: Exact match for the user’s locale (es_MX.json for Spanish - Mexico)
2. Second try: General language file (es.json for Spanish)
3. Last try: Default language file (en.json for English)

• The translation file doesn’t exist
• The translation key isn’t in the file

​

Translation key types

{
  "welcome": "Welcome!",
  "goodbye": "See you later!"
}

{{t "welcome"}}           <!-- Normal key -->

{
  "title": "Welcome to our app",     // Auth page title
  "title": "Order confirmation"      // Order page title - CONFLICT!
}

​

Setup

1

Upload translation files

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

2

Set user locale

Set the user’s locale via API. The older method used preferred language, but you can now use locale directly with $set_locale action or $locale parameter. The locale determines which translation file SuprSend will use for that user’s notifications.Example:

Copy

Ask AI

{
  "$set_locale": "en_GB"
}

Use standard ISO locale codes like en_US, es_ES, fr_FR, en_GB, etc.

3

Use in templates

Add translation keys to templates using the {{t}} tag:

Copy

Ask AI

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

🎉 Notifications will now automatically display in each user’s preferred language.

​

Using translations in templates

Subject: {{t "welcome"}}
Body: {{t "goodbye"}}

{
  "welcome": "Welcome!",
  "goodbye": "See you later!"
}

  {{t "auth:login"}}
  {{t "orders:status"}}

{
  "auth:login": "Sign in to continue",
  "orders:status": "Order status"
}

​

One template for all languages

• Layout inconsistencies when updating styles across multiple files
• Increased maintenance when fixing bugs or making design changes
• Risk of forgetting to update all language versions

<div class="welcome-card">
  <h1>{{t "welcome_title"}}</h1>
  <p>{{t "welcome_message" name=user.first_name}}</p>
  <button>{{t "get_started"}}</button>
</div>

templates/
├── welcome_en.html
├── welcome_es.html
├── welcome_fr.html
└── welcome_de.html

​

Managing translation files

​

Translation process

1. Make changes - Add, edit, or delete translation files in the dashboard
2. Review drafts - All changes are saved as drafts until committed
3. Commit changes - Commit translations to make them live
4. Version control - Every commit creates a new version with full history

​

Add new translation files

1

Navigate and select file

Go to Developers → Translations. Upload your JSON translation file and verify the file structure matches the required format.

File naming: Use correct naming convention (en.json, es_MX.json, or auth.en.json for namespaced files).

2

Upload file

Click the Next button to add the file.

3

Commit changes

Click Commit to make the translation file live.

​

Edit existing translation files

1

Open translation file

Go to the translation file you want to edit.

2

Download file

Click Download to save the translation file locally for editing.

3

Edit, upload and commit

Make your edits to the downloaded JSON file, then click Upload to replace the existing file. Finally, click Commit to make your translation changes live.

​

Delete translation files

1

Delete file

Find the translation file you want to remove, and click Delete.

2

Commit deletion

Click Commit to publish the deletion.

​

Version control

1

Open version history

Go to Developers → Translations, click on a translation file, then open the Version History tab.

2

Select and rollback

Select the version you want to restore and click Rollback. Confirm the action.

3

Commit changes

Click Commit to make the rollback live.

​

Automating translation with CLI

​

Translation Management APIs

​

Supported locales

​

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

​

Troubleshooting