Add Feature for Easy Access to Keywords in Docs Glossary

[mboukhalfa]

As I work on localizing Kubernetes documentation into Arabic using the Docsy theme, I've encountered a significant opportunity to improve the readability of localized documents.

When translating documentation from English to another language, one common challenge is finding suitable translations for keywords. Often, the translated term is either unfamiliar or lacks a unified translation, leading to the retention of the English term or the awkward usage of both the translated term and its English counterpart in parentheses.

To address this issue, I propose the following enhancement:

I suggest implementing a feature that allows users to easily access the English term when they encounter an unfamiliar translated term. One approach could involve enabling users to hover over the translated term, triggering a clean and unobtrusive tooltip display of the corresponding English term, similar to Bootstrap tooltips.

How Docsy can implement this:

To streamline this process with Docsy, we could leverage a glossary for localization. By creating a glossary that links English terms with their translations, we could utilize shortcodes in Docsy to automatically generate tooltips for terms listed in the glossary. This approach would not only facilitate comprehension for users encountering unfamiliar terms but also provide an efficient means for users to access glossary definitions without leaving the current page.

I envision a straightforward process where I provide a glossary in JSON format and invoke a simple Docsy function. This function would generate tooltips for the keywords in the glossary that exist in a selected text.

Implementing this feature would greatly enhance development with Docsy and the user experience of localized documentation, ensuring clarity.

[fekete-robert]

The falco docs have something similar that uses two shortcodes and stores the definitions in a language-specific folder (https://github.com/falcosecurity/falco-website/tree/master/content/en/docs/reference/glossary)

[mboukhalfa]

The falco docs have something similar that uses two shortcodes and stores the definitions in a language-specific folder (https://github.com/falcosecurity/falco-website/tree/master/content/en/docs/reference/glossary)

How can I see this behavior directly on the website ?

[fekete-robert]

For example here, in the second paragraph: https://falco.org/docs/getting-started/

[mboukhalfa]

For example here, in the second paragraph: https://falco.org/docs/getting-started/

Yeah exactly what I had in mind I just want to implement this to link translated terms with the English ones so if the reader come across unfamiliar translated term can easily refer to the English one

[sftim]

We already have glossary tooltips, but only where the author has added them. We could add a similar mechanism for providing hints to people reading localized pages.

I wouldn't use JSON for that though.

[mboukhalfa]

We already have glossary tooltips, but only where the author has added them. We could add a similar mechanism for providing hints to people reading localized pages.

I wouldn't use JSON for that though.

The idea behind using JSON or some formatted data as input is to automate the process, it will be hard for the developer to find out all the the words added to the glossary and maintain them some sort of short code would automatically analyze the text and find the words that exist in the glossary and add tooltip for the English equivalent