Notifications

[JanCizmar]

1. Problem

Currently, translators and reviewers in Tolgee are not automatically notified when new keys are added, translations are created, or reviews are needed. Developers or project managers have to manually inform translators, which causes delays and friction in the translation process.

This is especially painful for larger teams or companies with in-house translators or reviewers. They need a smooth workflow where the right people are notified automatically.

Desired Outcome

• Translators and reviewers are automatically informed about relevant events (new keys, translations to review, comments, mentions).
• Notifications reduce manual coordination and improve translation speed.

Business outcomes

• This helps us reduce churn (fewer frustrated customers) and improves acquisition of larger companies who expect notification workflows.
• Reduced churn, higher conversion rate, less support requests

---

2. Appetite

How much time do we want to spend on this?

Appetite: One cycle.

---

3. Solution

We already have a notification system in place for tasks, including web socket updates visible in the UI. We will extend this system to support new notification events and deliver them by email as well.

Core notification types

Users should be able to configure which notification types they want:

• New keys added
• Strings translated
• Strings reviewed
• Mentions in comments (notify mentioned users)

Notification logic

• Notifications should be sent as soon as possible, but batched to avoid spamming. Example: wait ~5 minutes before sending the first batch; show the notification first in the UI and only after 10 minutes send the e-mail; don't send another e-mail for the same event type within the same day; if the user views the notification, go back to the beginning.
• Users with the web app open will receive live updates via WebSocket.

Technical design direction

• Hook notifications into the existing activity logging mechanism. (ActivityRevision entity etc.) This is the most consistent place to detect events, as localization data changes come from many service methods.
• Notifications must be reliable. If a node shuts down (e.g. crash, power loss), pending notifications should still be sent after restart. → Consider storing notification state or “pending events” in a persistent store (e.g. activity_revision table).
• Must be configurable for each notification type.

UI considerations

• We can reuse existing UI for notifications.
• Only small additions in settings are needed (to configure notification types).

Documentation

As this is kind of an interview task, we would like to see documentation created before the end of the "Super Week"

---

4. Basic Drawings

No mockups are necessary at this stage.

@ZuzanaOdstrcilova can provide drawings if required.

---

5. Rabbit Holes

What are the potential complexities, unknowns, or risky areas?

• The most complex rabbit hole is to wire this functionality to the Activity Logging system and keeping it reliable so it's persistent.
• The nodes in cluster should not handle the same notifications resulting in notifying user about same event multiple times

---

6. No-Goes

• Do not rebuild the existing activity log UI or backend.
• Do not add new notification channels beyond email and WebSocket.
• Do not handle every possible event. Start only with keys, translations and mentions.

---

7. Success Criteria

Success = fewer complaints about missing notifications. We’ll know it works when:

• Translators and reviewers are automatically informed.
• Support requests about “missing notifications” disappear.
• Internal feedback confirms notifications are reliable and non-spammy.

[SAIRAMSSSS]

I would like to take this on as my first contribution to the project. I'll start looking into a fix and open a pull request soon. Please let me know if there's any specific guidance you have,Assigning this to me would be great if that's possible!

[jdimeo]

How does this relate to https://github.com/tolgee/tolgee-platform/issues/2244?

[JanCizmar]

Hello John!

Thanks for the question! 😊

Both #2244 and this pitch aim to improve how Tolgee notifies people. They share a few key ideas:

• Both plan to automatically notify translators and reviewers when something important happens, like new keys being added, translations being created or reviewed, or when someone is mentioned in a comment (Feature you're waiting for! I know 🚀).
• Both expect to batch notifications (show them in the app first and send email summaries later) to avoid spamming people.
• Both let users choose which notifications they want to get and will hook into the existing activity log rather than building a whole new system.

The big difference is scope. #2244 covers a full redesign of the activity dashboard, new filters and views, email digest templates, Discord integration, and other wishlist features . The current pitch is a simplified first step that focuses only on adding key notifications and comment mentions. We want to ship this quickly because it solves the pain our users feel today: translators and reviewers not knowing when to act.

[davidhosek]

Scopes

Config

• [x] Add notification types configuration
• [x] Add notification types to UI
• [ ] Make strings with translations for new items

Activity automation

• [x] Create activity automation for handling events
• [x] Fetch activity details
• [x] Create batch job for activity

Batch job executor

• [ ] Aggregate activity batch jobs
• [ ] Fetch users to be notified
• [ ] Notify users via UI WebSocket
• [ ] Create batch job for e-mail send
• [ ] Get seen notifications and prepare rest for e-mail
• [ ] Notify users via e-mail

Docs

• [ ] Create tech docs
• [ ] Update official Tolgee docs

[github-actions[bot]]

This issue is stale because it has been open for 30 days with no activity.