Glossaries

[JanCizmar]

1. Problem

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

Users want to fix and standardize their terminology across projects and mark certain terms as “non-translatable” to keep translations consistent.

---

2. Appetite

How much time do we want to spend on this?

We have allocated one 6-week cycle to implement the glossaries feature.

---

3. Solution

How do we imagine solving this problem?

• Allow creating and managing organizational-level glossaries that can be linked to projects.
• Provide import/export capabilities for glossary entries. On import, users can choose to overwrite or keep existing terms.
• Add a dedicated permission checkbox at the organization level, so only authorized users can manage glossaries.
• Enable marking terms as “non-translatable,” “case-sensitive,” and implementing the required functionality
• Make it possible for translators to quickly see and reference these glossary terms in context.

---

4. Basic Drawings

What rough sketches or wireframes illustrate the concept?

We have basic designs showing:

1. A “Glossaries” section where users can create and edit glossaries.
2. A table-like view listing terms with their translations in multiple languages.
3. Options for importing/exporting and a prompt for overwriting or keeping terms during import.
4. A permission settings screen with a checkbox to grant “Manage Glossaries” access.

---

5. Rabbit Holes

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

• Handling language tags when users may define custom ones (BCP-47 compliance is optional).
• Detaching a glossary from a project when the project is transferred to another organization.
• Defining how to treat empty target values (e.g., if a glossary entry is missing a translation).
• Visual representation of undefined target translations in the UI.

---

6. No-Goes

What explicitly falls outside the scope of this pitch?

• Conflict resolution logic during import (beyond “overwrite vs. keep”).
• Handling multiple word forms, cases, or partial matches.
• Project-to-glossary language mapping beyond simple direct matches.
• Support for tagging glossary entries (beyond basic checkboxes).
• AI-generated entries or machine translations for glossary terms.
• Complex linguistic forms or QA checks related to terminology usage.

[ZuzanaOdstrcilova]

Here is the link to Glossary design: https://www.figma.com/design/UYsyo57SCcWFpyMirhGmv4/Tasks-2025?node-id=47-2355&t=xUxBWNiPVElPh7iq-1

[jdimeo]

One thing to keep in the back of your minds are the similarities/differences with a business glossary, as found in many popular data catalogs. For example: https://atlan.com/what-is-a-business-glossary/

We will likely be bi-directionally integrating our business glossary with Tolgee's glossary once it exists. I of course don't expect anything out of the box here, but if they were conceptually aligned that would be nice.

[Anty0]

Progress - aka. Scopes (WIP)

Glossaries

• The UI shows the "Glossaries" section in the organization configuration page
• The UI lists glossaries
• The UI allows the creation a glossary
• The UI allows deleting a glossary
• The list of glossaries is using paging
• I think I know how to do it
• I have validated my approach
• ~Display all used languages in the list (currently only the base language is displayed)

Glossary terms

• The UI lists glossary terms
• The UI allows adding a glossary term
• The UI allows deleting a glossary term
• The UI allows changing which languages are to be displayed (list of available languages automatically composed of all languages of all organization projects and all languages in use by the glossary - limitation of the first iteration of the glossaries feature)
• The UI allows translating the glossary term
• The UI allows clearing (deleting) glossary translation
• The list of glossary terms is using paging
• I think I know how to do it
• I have validated my approach

Term highlighting

• The UI highlights matching terms in the translation view
• The UI shows the glossary term description when hovering over the highlighted term
• The UI shows found glossary terms in the right sidebar
• I think I know how to do it
• I have validated my approach

Tolgee AI translator

• Tolgee AI translator takes glossaries into account when translating text
• Only glossary terms in the base text are considered
• I think I know how to do it
• I have validated my approach

~Import

• The UI allows importing a glossary from a CSV file
• I think I know how to do it
• I have validated my approach

~Export

• The UI allows exporting the glossary to a CSV file
• I think I know how to do it
• I have validated my approach

Permissions

• It is possible to allow glossary management for organization members selectively
• I think I know how to do it
• I have validated my approach

Activity logging

• Changes to glossaries are logged to the activity log (no frontend UI will be available to access this log as part of the first iteration)
• I think I know how to do it
• I have validated my approach

Rabbit holes (in addition to the list above)

• Permission handling: (New maintainer role pretty much solves this)
  • My understanding of the current permission system is low
  • Glossaries are owned by the organization, which might not fit well with the permission system design - needs research on my side
• Highlighting (Greatly reduced by only supporting highlighting in "view" mode and not in editor)
  • Will need more research on my side into how the current component responsible for displaying and editing translations works

Notes/Questions/Uncertainties

• Implement as OSS or EE as an optional feature
  • Implement in EE
• CSV file format - do other services use some standard column names? research needed
• How does the user get to the glossaries list page? - Design will need to be consulted with @JanCizmar and @ZuzanaOdstrcilova
  • Section in organization settings for now
• Tolgee AI support as part of the first iteration?
  • Yes
• Where can the user specify glossary languages?
  • We will use all languages with existing glossary translations and all languages available in any project managed by the organization (the first iteration limitation)
• Multiple glossaries can be assigned to a single project?
  • Yes
• Assumption: When passing glossary metadata to the Tolgee AI translator, only glossary terms found in the base text will be considered. Is this the correct approach?
  • Yes
• (If the final design contains a glossaries button in the project side menu.) Should we only list glossaries assigned to that project?
• Can we release an API for fetching metadata needed to highlight glossary terms in translations as beta/unstable? It will need to be reworked as part of QA checks later, so supporting this first iteration of the API longterm doesn't make sense.
• Edit glossary design - gotta ask @ZuzanaOdstrcilova what is the best approach.
• My current implementation returns a lot of duplicated info through API. Maybe it should be reduced and frontend should be modified to use context to pass this info instead.
  • Implemented context for a glossary
• Current implementation uses softDelete for Glossaries. Maybe this is overkill and we can switch to normal full delete? Terms and their translations use full delete.

[JanCizmar]

Points from demo

• Make it more compact in the translations view
• Make the terms table cell less wide, so I can see more languages in the same time
• Document the language and base language behaviour, add some in-app docs, tooltips or whatever to make it clear for the user
• Add tooltips to the flags
• Fix the empty state, keep controlling elements (search, filters) so it's clear we are in specific glossary
• Sorting, ~Cursor
  @ZuzanaOdstrcilova @Anty0