Widget Translations

The Widget Translation Management system allows you to create multilingual widgets that automatically display content in the user's preferred language. This comprehensive translation system provides a table-based UI for managing translations across multiple languages with ease.

Overview

Widget translations enable you to:

• Define translation keys and values for multiple languages
• Use a table-based interface with inline editing
• Navigate efficiently using keyboard shortcuts (Tab/Enter)
• Automatically detect translation keys used in your widget layout
• Support any language code (e.g., en, de, fr, es)

Accessing the Translations Tab

1. Navigate to your widget editor
2. Click on the Translations tab
3. Start by adding your first language

Managing Languages

Adding a Language

1. Click the Add Language button
2. Select a language from the dropdown (e.g., English, German, French, Spanish)
3. Or enter a custom language code (e.g., pt-BR for Brazilian Portuguese)
4. Click Add to create the language column

Removing a Language

1. Click on the language code header in the table
2. Select Delete Language from the dropdown menu
3. Confirm the deletion

warning

Deleting a language will remove all translations for that language. This action cannot be undone.

Managing Translation Keys

Adding a Translation Key

You can add translation keys in two ways:

Method 1: Manual Entry

1. Click in the "Click to add" field at the bottom of the table
2. Enter your translation key (e.g., greeting, button.submit, error.message)
3. Press Enter to create the key
4. Click on the cells to add translations for each language

Method 2: From Layout Detection

The system automatically detects translation keys used in your widget layout using Handlebars AST parsing. Missing keys are highlighted in amber at the top of the table:

1. Keys detected in your layout appear with an amber background
2. Click on any cell to add a translation
3. Use the + button to add the key to all languages at once

Key Naming Convention

Use descriptive, hierarchical key names:

• greeting - Simple keys
• button.submit - Nested keys using dot notation
• error.notFound - Categorized keys

Editing Translations

1. Click on any cell to start editing
2. Type your translation text
3. Press Enter or Tab to save and move to the next field
4. Press Escape to cancel editing

Keyboard Navigation

The translation table supports efficient keyboard navigation:

Key	Action
Tab	Save current cell and move to the next cell (right)
Shift + Tab	Save current cell and move to the previous cell (left)
Enter	Save current cell and move down to the next row
Escape	Cancel editing and close the input

Efficient Workflow

When adding translations row by row, use Enter to move down. When translating across languages, use Tab to move right. On the last row, pressing Enter will automatically focus the "new key" input field.

Deleting Translation Keys

1. Click the trash icon in the Actions column
2. Confirm the deletion
3. The key will be removed from all languages

Using Translations in Your Widget

The t Handlebars Helper

Use the {{t 'key'}} helper in your widget layout to display translated text:

<!-- Simple translation -->
<h1>{{t "greeting"}}</h1>

<!-- Nested keys with dot notation -->
<button>{{t "button.submit"}}</button>

<!-- In attributes -->
<input placeholder="{{t 'form.email.placeholder'}}" />

<!-- In conditional blocks -->
{{#if error}}
  <p class="error">{{t "error.message"}}</p>
{{/if}}

Language Detection

The widget automatically uses the appropriate language based on:

1. Staffbase Branch Configuration - The primary language set in your Staffbase environment
2. Browser Language - Falls back to the user's browser language if configured
3. Default Language - Uses the first language in your translations if no match is found

Example Translation Setup

Here's a complete example of a multilingual widget:

Translation Keys:

Key	English (en)	German (de)	French (fr)
greeting	Hello!	Hallo!	Bonjour!
button.submit	Submit	Absenden	Soumettre
button.cancel	Cancel	Abbrechen	Annuler
message.success	Successfully saved!	Erfolgreich gespeichert!	Enregistré avec succès!

Widget Layout:

<div class="widget">
  <h1>{{t "greeting"}}</h1>

  <form>
    <button type="submit">{{t "button.submit"}}</button>
    <button type="button">{{t "button.cancel"}}</button>
  </form>

  {{#if saved}}
    <p class="success">{{t "message.success"}}</p>
  {{/if}}
</div>

Automatic Layout Key Detection

The translation system uses Handlebars AST (Abstract Syntax Tree) parsing to automatically detect all {{t 'key'}} helpers in your widget layout.

How It Works

1. The system parses your Handlebars template
2. Identifies all t helper calls
3. Extracts the translation keys
4. Highlights missing keys in amber at the top of the translation table

Missing Keys Indicator

When keys are detected in your layout but not in your translation table:

• An amber warning banner shows the count of missing keys
• Each missing key appears as an amber row at the top of the table
• You can add translations directly or use the + button to add to all languages

Layout Scanning

The system automatically scans your layout whenever you switch to the Translations tab or modify your template. Keys used in conditionals {{#if}}, loops {{#each}}, and nested helpers are all detected.

Best Practices

Organization

• Group related keys using dot notation (e.g., form.email.label, form.email.placeholder)
• Use consistent naming conventions across your widgets
• Keep translation keys descriptive and self-documenting

Maintenance

• Add all languages before starting translations to avoid incomplete coverage
• Regularly check for missing layout keys (amber highlighted rows)
• Use the keyboard shortcuts for faster data entry

Quality

• Keep translations concise to fit within your widget design
• Test your widget in all supported languages
• Ensure translations maintain the same meaning and tone

Performance

• The translation system is optimized for runtime performance
• Translations are bundled with your widget (no additional API calls)
• Multiple languages don't impact widget loading time

Common Use Cases

Multi-Language Forms

<form>
  <label>{{t "form.name.label"}}</label>
  <input placeholder="{{t 'form.name.placeholder'}}" />

  <label>{{t "form.email.label"}}</label>
  <input placeholder="{{t 'form.email.placeholder'}}" />

  <button>{{t "form.submit"}}</button>
</form>

Error Messages

{{#if errors}}
  <div class="errors">
    {{#each errors}}
      <p>{{t this}}</p>
    {{/each}}
  </div>
{{/if}}

Dynamic Content

<h2>{{t "welcome"}} {{user.firstName}}!</h2>
<p>{{t "notifications.count"}} {{notifications.length}}</p>

Troubleshooting

Keys Not Detected

If your translation keys aren't being detected automatically:

• Ensure you're using the correct syntax: {{t 'key'}}
• Check that your layout doesn't have syntax errors
• Verify the key is wrapped in single quotes: 'key' not "key"

Translations Not Showing

If translations aren't displaying in your widget:

• Verify the key exists in at least one language
• Check the browser console for errors
• Ensure your widget is using the latest version

Missing Translations

If a translation is missing for a specific language:

• The system will fall back to the first available language
• Consider adding a default language with all keys defined
• Check the amber highlighted rows for missing translations

Additional Resources

• Widget Builder Layout Documentation
• Handlebars Helpers Reference

Need Help?

If you encounter issues with the translation system, contact support or check the Widget Builder documentation for more detailed examples.