Translations

​

How translations work

​

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

1. Exact locale match — for example, es-MX.json
2. General language file — for example, es.json
3. Default language fallback — for example, en.json

​

Basic usage

{
"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 !"
}

{{t "task_created" task_name=task.name}} 
{{t "task_completed" task_name=task.name}} 

{ 
  task_created: t("task_created", {task_name: task.name}), 
  task_completed: t("task_completed", {task_name: task.name}) 
} 

​

Managing translation files

​

Flow

​

Directory structure

1. By locale code — one file per language, for example en.json, fr.json
2. By namespace + locale code — group translations by feature or module within the same language, for example 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.

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

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.

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.

​

Update existing files

1

Download file

Click Download to save the translation file locally for editing.

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

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.

2

Commit deletion

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

​

Version history and rollback

• 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.
  

​

Using translations in templates

​

Simple, Nested and Namespaced keys

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

{
  simple_key: t("key_name"),
  namespaced_key: t("feature:key_name"),
  batched_key: t(data["$batched_events"][0].name)
  nested_key: t("nested_key.sub_key")
}

​

Pluralization

{
  "tasks": {
    "zero": "You have no tasks",
    "one": "You have 1 task",
    "other": "You have {{count}} tasks"
  }
}

• count = 0 → uses zero form → "No items"
• count = 1 → uses one form → "1 item"
• count ≥ 2 → uses other form → "5 items"

{{t "tasks" count=$batched_events_count}}

{
  tasks: t('tasks', {count: data["$batched_events_count"]})
}

​

Interpolation

{
  "greeting": "Hello, {{name}}!"
}

{{t "greeting" name=$recipient.name}}

{
  greeting: t('greeting', {name: data["$recipient"].name})
}

• “Hello, John!” when $recipient.name is “John”

​

Combining with Handlebars helpers

1. Default value

{{default (t "name") "Guest"}} 

2. Conditional rendering

{{#if user.is_premium}}
{{t "premium_plan.details"}}
{{else}}
{{t "standard_plan.detail"}}
{{/if}}

3. Looping

{{#each $batched_events}}
{{t "item_name"}}
{{/each}}

​

Automate translation with CLI and APIs

• CLI
• Management API

​

Supported locales

​

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