Communardo Software GmbH, Kleiststraße 10 a, D-01129 Dresden

Change system language with CUTE

A short 5-step-guide how to use the Confluence add-on CUTE to easily make a system language switch without knowledge in the Confluence plugin development.

During my daily work with Confluence I often need some kind of func­tio­n­a­lity more than other kinds. In those moments, I wish these func­tions can be easier and fas­ter to achieve. This is espe­cially true if the click path is very long. One such case is the change of the Confluence sys­tem lan­guage of my cur­rent user account.

But you can meet this requi­re­ment quickly by using CUTE. For this, I need no know­ledge in the Confluence plugin deve­lo­p­ment. It is enough if I am fami­liar with Velocity, Javascript and CSS.

Step 1: Creating a new extension

After the instal­la­tion of the plugin using the Atlassian Marketplace, I can start right away. Via glo­bal Administration > CUTE  the con­fi­gu­ra­tion view of the tool appears. Here I choose "Add Extension" and fill in a name and a uni­que key for my extension.

After this, I can finally begin working on the exten­sion by cli­cking "Edit".

Step 2: Generate a list of all con­flu­ence instal­led languages

First of all, I need the infor­ma­tion which lan­guage ver­si­ons are actually instal­led in the con­flu­ence sys­tem. For this pur­pose, I search in the Atlassian Confluence API and promptly find the LanguageManager that pro­vi­des the method "getLanguages​​". So I create a new tem­plate resource in my extension.

With this, I can create any struc­ture using HTML and Velocity. The code will be inser­ted auto­ma­ti­cally to all pages and is hid­den by default. I con­clude that the list of lan­guages should be loca­ted in the glo­bal navi­ga­tion bar of Confluence. So I look at the exis­ting glo­bal Confluence menu and create my own struc­ture simi­lar to this. Furthermore, I'll get the LanguageManager directly inside the tem­plate by using the pro­vi­ded ser­vice "applicationService" and its method "getComponent":

#set($languageManager = $applicationService.getComponent("com.atlassian.confluence.languages.LanguageManager"))

I want to use no text for the top menu item. So I look for a mea­ning­ful logo and add this to the exten­sion. Below the added logo, a path appears which I can sim­ply import into my template.


This is the final tem­plate code for my lan­guage list menu:

#set($languageManager = $applicationService.getComponent("com.atlassian.confluence.languages.LanguageManager"))
<div id="cutelanguagebox">
    <li id="cutelanguagemenuwrapper">
        <a id="browse-cutelanguages-link" href="#">
                <img id="cutelanguage-icon" src="@contextPath/plugins/cute/static/resource/communardo.language.switch/globe.png" >
        <div hidden="">
                #foreach( $language in $languageManager.languages )
                        <a href="#" locale="$" title="">

Step 3: Moving the tem­plate Container

The tem­plate code is now embed­ded in every page (except the admi­nis­tra­tion views). However, it is hid­den and needs to be moved to the appro­priate loca­tion by using Javascript. So I create a new java­script resource.


Since I have mar­ked my navi­ga­tion in the tem­plate code with the id "cut­e­lan­gu­age­box", I can now sim­ply move the con­tai­ner to the navi­ga­tion menu and re-initialize the menu after­wards. Here is the java­script code:

AJS.toInit(function() {
    jQuery("#header-menu-bar").prepend( jQuery("#cutelanguagemenuwrapper"));

    //reinitialize menu after modification
    jQuery("#header-menu-bar *").unbind();
        isFixedPosition : true

Step 4: Change the sys­tem language

The change of the sys­tem lan­guage after cli­cking on one of the lan­guage menu items is done by using java­script. I use the same action as it is used in the user pro­file con­fi­gu­ra­tion. For this I use a new java­script resource which exe­cu­tes an AJAX request in the back­ground. If this was suc­cess­ful, I rel­oad the page using Javascript. Here's the code:

AJS.toInit(function() {
    jQuery("#cutelanguagemenuwrapper .cutelanguagelink").click( cuteChangeLanguage);

function cuteChangeLanguage() {"/users/doeditmysettings.action", {atl_token: jQuery("#atlassian-token").attr("content"), preferredUserLocale : jQuery(this).attr("locale")}, function(data){
    return false;

Step 5: Polish the edges

Now, the result can be seen. However, the icon is too big for the top navi­ga­tion bar. This can be fixed by using a little bit of CSS. I add a new style sheet resource.


In there, I define a style that brings up the icon to a good size. Here is the CSS:

#cutelanguage-icon {
    width: 20px;
    vertical-align: middle;

The Result


And thats it! The new menu item in the glo­bal navi­ga­tion fits great into the exis­ting style and also works with the other default the­mes (Documentation and Easy Reader). In addi­tion, the exten­sion is com­pa­ti­ble from Confluence 3.4 up to Confluence 4.2. This is ensu­red by the mini­mum enga­ge­ment of the sys­tem. The chance of com­pa­ti­bi­lity with new ver­si­ons is very high because there was no plugin deve­lo­ped which over­ri­des cen­tral Confluence templates.

The exten­sion its­elf can now be easily expor­ted and impor­ted to any other Confluence system.

Copy it and make it more beautiful!

I have stored the exten­sion to our sup­port por­tal so you can use it on your own sys­tem. It is a good star­ting point for exten­si­ons going in a simi­lar direction.

22. August 2012

Related Posts

Pin It on Pinterest