This document describes how to build and use a multi-lingual (English, Korean, Japanese, and Chinese languages are supported), global glossary in Confluence. The terminology hosted in this glossary can then be presented to users in any documentation page in the appropriate language.

The solution is based on having a Scroll Versions-managed Source Glossary Space where terms and their definitions are stored (1 term per page) – the content of the Source Glossary is then published using Scroll Versions to separate Target Glossary Spaces, one per language. From there, you can pull the terms from the Target Glossary Spaces using custom macros.

First steps

 Click here for the code
#*
Copyright (c) 2017 Medidata Solutions, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. 

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*#


## Author: Alex Yasurek
## Name: glossary-popup-macro
## Title: Glossary popup macro
## Macro body: No Macro body

## @param Page:title=Page|type=confluence-content|required=true|desc=Enter page to extract glossary definition from
## @param Title:title=Word to use|type=string|required=true|option-showNameInPlaceholder=false|option-showValueInPlaceholder=true|desc=Enter word defined

##Get excerpt macro from page user selected
#set ($definition = $action.getHelper().renderConfluenceMacro("{excerpt-include:$paramPage|nopanel=true}"))

##check to see that text does not contain name of page or is empty 
##(either means term was not translated yet)
#if($definition.contains($paramPage) || "$definition" == "")
 
    #set($first = true)
    #foreach ($p in $paramPage.split(":"))
        #if($first)
            #set($spaceKey = $p )
            #set($first = false)
        #else
            #set($pageName = $p)
        #end
    #end

    ##based on space they were trying to pull term from, add message saying term is not 
    ##translated yet then put definition in english
    #if($spaceKey.equals("GLOSSARYprdJPN") )
        #set($introMsg = "(翻訳準備中)" )
    #elseif($spaceKey.equals("GLOSSARYprdKOR") )
        #set($introMsg = "(한국어 준비 중)" )
    #elseif($spaceKey.equals("GLOSSARYprdCHN") )
        #set($introMsg = "(翻译在进行中)" )  
    #end

    #set($engPage = "GLOSSARYprdENG:${pageName}")

    #set($engText = $action.getHelper().renderConfluenceMacro("{excerpt-include:$engPage|nopanel=true}") )
    ##some single quotes cause text on page to get mangled so turn them to html entities
    #set($definition = $engText.replaceAll("'", "’"))

    <span class="glossaryQtip" title='$!introMsg $definition'>$paramTitle</span>
#else
    #set($definition = $definition.replaceAll("'", "&rsquo;"))
    <span class="glossaryQtip" title='$definition'>$paramTitle</span>
#end
CODE
 Click here for the code
//This goes in the custom html section in the confluecne admin area.
//Qtip library is what will make definition popup when hoving over a word on a page


<link type="text/css" rel="stylesheet" href="https://cdn.jsdelivr.net/qtip2/2.2.1/jquery.qtip.min.css" />
<script type="text/javascript" src="https://cdn.jsdelivr.net/qtip2/2.2.1/jquery.qtip.min.js"></script>


<script type="text/javascript">

AJS.toInit(function() {


$('span.glossaryQtip').qtip({
    style: { classes: 'customQtip' },
    position: {
        target: false, 
        viewport: true, 
        adjust: {
          method: 'flip flip' 
        }
    },
    hide: {
        delay: 1000,
        event: 'mouseleave',
        fixed: true
    },
    events: {
         render: function (event, api) {
            var id = api.get("id");
            $("#qtip-"+id+"-content a").each(function(){
                //console.log($(this).attr("href"));
                $(this).attr('target', '_BLANK');
            }); 
        }
    }
});

});

</script>
CODE

Create and prepare a source glossary space

The first step is to create a new Source Glossary Space. This space will be the home of all the terms and their definitions, in all languages.

Prepare the Source Glossary Space:

  1. Activate Scroll Versions in the Source Glossary Space
  2. Activate permalinks in the Source Glossary Space
  3. If you want to create a multi-language glossary, activate Scroll Translations in the Source Glossary Space, and add any languages you want to translate to. Please bear in mind that only 4 languages are supported – English, Korean, Japanese, and Chinese.

Create glossary terms

Now, let's create the glossary terms in the Source Glossary Space.

  1. Create a new page for the glossary term (in this method, each term is kept on its own page)
  2. Enter the term name as the page title
  3. Insert an Expand macro onto the page, and use the term name as the macro title
  4. Insert an Excerpt macro inside the Expand macro. The excerpt macro should include the definition of the term.
  5. Add the following page labels to the page:
    1. First letter of the term (in each language if they are translated)
    2. The label of any products they may belong to
    3. Any other label that you might want to use to filter the glossary terms by when they are listed
  6. Add any further terms that you need, and translate the terms if needed.

Publish glossary terms to a Target Glossary Space

Now we've created the glossary terms, we can publish them to the Target Glossary Space. The Target Glossary Space is where authors will pull the definitions from when including glossary terms on pages.

  • Publish the Source Glossary Space in a single language to a new space, with the following settings:
    • The Target Glossary Space must have a space key that follows this standard: GLOSSARYprd<3-letter language abbreviation>. E.g.: GLOSSARYprdENG
    • Select the Copy labels publish setting
    • If Scroll Translations is activated in the Source Glossary Space, select the Keep permalinks publish setting

Display glossary content in production spaces

There are two ways of displaying glossary content in production spaces:

  • Use the Glossary Content by Labels macro to pull all terms from a Target Glossary Space, and include them based on label.
  • Use the The Glossary Pop-up macro to have a definition of a term pop up when a user hovers over that term.

Glossary Content by Labels macro 

Configure the macro

After inserting the Glossary Content by Labels macro where you want to insert the list of glossary terms, you need to configure the macro. There are three fields to configure:

FieldDescription
LabelEnter all the labels you want to search for. Each label needs to be separated by a comma
Glossary Spaceuser selects the glossary space they want to pull the terms from. User uses this field to pick the language they want the terms to appear in.
Operator

Selects whether all the labels should be searched for using a "AND" or an "OR" operator.

  • AND means all the labels must appear on the term page
  • OR meaning at least one of the labels needs to appear on the term page

In this example, all terms that have the label 'a' and also have the label 'Balance' are being pulled from the English Glossary:


Glossary pop-up macro 

Where you insert the Glossary pop-up macro, a word is added to the page, which you can hover over to display a pop-up description.

Configure the macro

There are two fields to configure:

FieldDescription
PageThe page to extract the glossary definition from
Word to useThe word that will be inserted on to the page

In this example, the word Randomization is added to the page, with the definition for the word Randomization from the English-language Target Glossary Space:

In the Confluence page view, it will look like this: