The translation suggestions

[JanCizmar]

1. Problem

What is the core problem we are trying to solve? Why does this matter?

One of the users wanted to export last reviewed translation instead of the latest value, which can in the TRANSLATED state before someone reviews it.

We have discussed similar behaviour as part of the community translations feature. So user's would be able to propose new translations without the risk to changing exported strings in reviewed state without the permission to review.

---

2. Appetite

How much time do we want to spend on this?

Full 6 weeks cycle, since this will be not easy to implement and test and can be simple solution for the whole Community translations problem.

---

3. Solution

How do we imagine solving this problem?

1. Introduce a new “Suggestions” mechanism

   • When the project is in “Enforced” Mode for suggestions, any translation currently in a REVIEWED state cannot be directly edited by non-reviewers.
   • Instead, non-reviewers can add a suggestion that appears in a separate list for that key.
   • A reviewer can then accept or decline each suggestion. Accepting a suggestion updates the official translation; declining it leaves the reviewed translation as-is.

2. Project-level Settings

   • Off
     • Disables suggestions altogether. Editing works as it does today, simply changing the translation and state.
   • Optional
     • Behaves similar to the current flow. Users can either edit directly (causing the translation to move from REVIEWED to TRANSLATED) or optionally leave suggestions.
   • Enforced
     • The “new mode,” where non-reviewers are only allowed to create suggestions on a REVIEWED translation.

3. UI & Filtering for Suggestions

   • Filtering (in the translations view): Users can filter to see:
     • Keys that have any suggestions.
     • Keys that have unresolved suggestions (i.e., still pending acceptance or decline).
   • Suggestion Management: Each suggestion shows:
     • Author
     • Text content
     • Time of creation
     • Current status (pending, accepted, declined)
     • Reviewer actions (accept/decline)

---

4. Basic Drawings

What rough sketches or wireframes illustrate the concept?

┌─────────────────────────────────┐
│ Translation Key: "greeting"    │
│ Current State: REVIEWED         │
│ Current Value: "Hello!"         │
│                                 │
│ [Suggestion List]  → (separate  │
│    place or tab shows existing) │
│                                 │
│ Actions:                        │
│   a) Add Suggestion (no Review  │
│      permission, or user wants  │
│      to propose rather than edit)
│   b) Set Value (only if user    │
│      has Review permission)     │
└─────────────────────────────────┘

┌─────────────────────────────────┐
│ Translation Key: "greeting"    │
│ Current State: TRANSLATED       │
│ Current Value: "Hello!"         │
│                                 │
│ [Suggestion List]  → (separate  │
│    place or tab shows existing) │
│                                 │
│ Actions:                        │
│   a) Add Suggestion (any user)  │
│   b) Set Value (any user —      │
│      matches current behavior)  │
└─────────────────────────────────┘

┌─────────────────────────────────┐
│ Suggestions for "greeting"     │
├─────────────────────────────────┤
│ #1: "Hey there!"               │
│ Author: user123                │
│ Created: 2025-03-03            │
│ Status: Pending                │
│ [Accept] [Decline]             │
├─────────────────────────────────┤
│ #2: "Hello World!"             │
│ Author: user456                │
│ Created: 2025-03-04            │
│ Status: Accepted on 2025-03-05 │
│ by reviewer789                 │
└─────────────────────────────────┘

---

5. Rabbit Holes

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

• Clarifying "current value" vs. "suggested value."
  Ensuring the UI labels these clearly to avoid confusion.
• How to store it?
  • I guess creating the new Suggestion entity will be better than using the Translation entity. A lot of fields from the Translation entity would be left untouched.
• Pluralization:
  When updating the isPlural of the pluralArg name for the key, it has to be updated in each translation and newly also in each translation suggestion

---

6. No-Goes

What explicitly falls outside the scope of this pitch?

What explicitly falls outside the scope of this pitch?

• Advanced Import/Export Logic for Suggestions
  We won't be importing or exporting suggestions themselves in this iteration.
• Comments
• We don't want to enable comments or other metadata on the Suggestion level
• Notifications
• Would be useful in the future, but currently the activity/notification system is not suitable for this

[stepan662]

Scopes

Suggestion indication in translations list

• [x] There will be one suggestion visible in the list + the number of extra suggestions that are not visible
• [x] When user switches to plural or edits the base translation, all suggestions will be declined (but there will be a warning about this).

Full suggestion list in translation detail

• [x] List all "active" suggestions
• [x] List "declined", "accepted" suggestion (on some toggle)
• [x] Ability to accept or decline suggestion
• [x] Adding new suggestion (depending on project settings, off by default)

Activity

• [x] Changes to suggestions should be visible in activity
• [x] Maybe project settings asweel

Permissions

• [x] There will be a new scope suggest

Project settings

• [x] Suggestions mode: disabled, optional or enforced - will change what translator role can do.

Pricing

• [ ] Is this paid or free feature?

Plurals

• [ ] Behavior when key is changed to plural / non-plural

Imports

• [ ] Manual import should show reviewed translations as conflicts and when you don't have permissions to update them. Then just not giving you an option to override.
• [ ] Figma plugin push should always pass, but hint you that some translations can't be pushed.

[stepan662]

Design: https://www.figma.com/design/UYsyo57SCcWFpyMirhGmv4/Tasks-2025?node-id=1138-5712&t=cPHNPRAy3dJ1nzLm-0