Associations & Multilingual Support

 

 

Introduction

jDownloads supports Multi-language Categories and Downloads.  Setting up a new or converting an existing site to be a Joomla! multilingual site is now relatively straight forward .
If you have not already done that there is an excellent Joomla! article  https://docs.joomla.org/J3.x:Setup_a_Multilingual_Site that takes you through the entire process of setting up a new multilingual site from scratch in a step by step manner.    A more recent update is https://www.joomlashine.com/blog/create-multilingual-joomla-site.html
.
If you already have an existing site that you need to convert to multilingual then there are additional notes in Appendix 2 below where some stages in the process  are outlined.  Also you may find this article on converting a unilingual site to a multilingual site helpful.  Additional assistance might be to create a simple multilingual site in a test environment to see what it looks like in the backend to act as a guide. 

The purpose of this article is to note the jDownloads specifics and to illustrate the results.
It is assumed in this article that the Joomla! language translations are already installed. This uses Extensions - Language(s) - Installed.  This gets you to a page showing which Joomla! languages are installed, and on the control bar there is an joomla lang install button button that will allow you to select the Joomla! language.  This process is also decribed in the Setup a Multilingual site link above.

So once that is done the next step is to install the relevant jDownload languages, but note jDownloads is distributed with English and German already installed.  Language packs for extensions are installed just like any other extension, they do not use the Install Language as that is only used for Joomla! languages.  Please see the article on installing Language packs for jDownloads (opens in a new tab/window) or the brief note in Appendix 1.

In a multilingual site it is preferable that all content items, which includes jDownloads Categories and Downloads, should have a specific language set.  Setting the language of a content item to 'All' is however appropriate in some circumstances, a partcular example might be the Uncategorised caegory which is often used for Downloads awaiting allocation to another category.   In jDowloads the language options for Categories and Downloads are in entries Category Language and Download Language respectively.

There are some instances where text is set in the jDownloads backend so to make this language sensitive jDownloads supports the language 'plugins'
like {en-GB}some text{/en-GB}.  These are described further below in the section Other Text.

In principle if a site supports say three languages then there will be three sets of categories and three sets of Downloads.  This could also mean that there would be three sets of downloadable files which could be a significant space issue.

Note however that jDownloads supports Downloads where the downloadable file is actually in another Download.

Previously using this facility was only available in the Backend but with the 3.9 series it is also available in the Front End in the Files tab when editing or creating a new download as shown opposite.

other file01 other file02
In the jD 3.9 series the User Groups settings have been enhanced to allow 'Or from another Download' to be used in the front end.
See the article on User Groups Settings for more details.

Support for RTL languages

Support for RTL languages is available in jDownloads 3.9.7.x and higher
An example is shown opposite in Arabic Unitag.

Please note that the translations team have not completed their work yet.

rtl01
An additional CSS file, jdownloads_fe_rtl.css, is automatically loaded when when an RTL language is detected.
This additional CSS file may be exported, imported or edited in the same way as the other CSS files.

Adding Menus

When setting up a multilingual site a key stage is to setup a menu for each language and then later, after creating content, to add relevant menu items.

The image opposite illustrates the Menus set up in the example described below. 

It has the site Main Menu and 4 'language' based menus named ar-menu, de-menu, en-menu and fr-menu respectively. These will be used to add relevant menu items.  The 'Linked Modules' are created automatically.

menu main
NB the image above was actually taken after the menu items had been added. The main Menu should initialy just show 1 published item. The other menus would show 0 items initially.

Example Details

In this article a multilingual site with the four languages Arabic, English, French and German is setup.  To clarify the language used each article, category or Download title ends with -ar, -de, -en or -fr to indicate its language setting.
Assigning a language to a jDownloads Category and Downloads are by using the pull-down in the relevant option as indicated opposite.

select lang catselect lang download
Articles and Article Categories use option select lang art cat

The first step was to create an Article category and an Article for each language.  Similarly a top level jDowloads Category, each with two subcategories, were created for each language. Each sub  subcategory was populated with four downloads.

In the lists below 'xx' is either ar, de, en or fr.  There are:
  • 4 article categories entitled as 'Article Cat-xx'
  • 4 articles, one per article category, entitled as 'Test article-xx'
  • 4 top level jDownloads Categories entitled 'Test Dir-xx'
  • 8 subcategories, two per language, named as  'pdf files-xx' and 'zip files-xx'
  • each sub category then had 4 downloads each, again with the title ending in -xx, giving a total of 32 Downloads.
 In addition to the above there are several 'All' language jDownloads Categories , subcategories and Downloads in the example site.
The Article Categories, the articles themselves, the relevant jDownloads Catgories and subcategories, and the relevant Downloads were all associated with their counterparts in the other languages as described later in this article.

As an example the Downloads specifically denoted for the English language are shown below with their associations.
 downloads xx

Add Menu Items

Now that some content has been created we can add menu items to the Menus created earlier. The example menu item titles are shown in English together with an -xx in the text to denote the language. 

The image opposite shows the results of setting up a main English language menu with two language related article menu items and three jDownloads menu items.

Note that all that each menu item has been 'associated' with its other languages  counterpart as described later.
menu01
Click on Home for one of the menu items to denote it as the 'Home' item. It will show the relevant language flag to denote it as the Home item, it does not matter which menu item is used.

Add List All Cats

There is one final step that is very important in the menu item creation phase.

That is to create a jD 'List All Categories' Menu item in the Main Menu.

Note this has a language setting 'All' and it is usually set as a 'Hidden' menu item.

It is used by jDownloads when constructing links.  It is not used by users!
menu03

Hidding a Menu Item



To make a menu item 'hidden', click on the menu item in order to edit it as shown opposite.

menu04


Then select the 'Link Type' tab and set option 'Display in Menu' to No.

After clicking the button save and close button then the hidden label will be shown as part of the menu item.

menu06



menu05

Options - Frontend

There are only two jDownloads Option settings relating to a multilingual setup.  These are in the Frontend tab and are illustrated opposite.
 batch01

If 'Show Associations' is set to 'Yes', the associated flags or URL Language Code will be displayed in the frontend.
The 'Use Image Flags' option also appears allowing choice of showing either the flags of associated items or the content language code.

Notes on Downloads

Before discussing the multilingual associations, it is useful here to first recall what makes up a Download.  A Download obviously has a title, an alias, permissions, access level, user access, a publication status, a language attribute and it is located in a category.  Optionally it may also have descriptions, symbols, images, previews, price, licence and many other items.  All of these are stored in the database.  Usually, but not always, a Download includes a downloadable file.  The downloadable file is not in the database. In most cases it is stored on your site in the directory jDownloads, but it may also be stored on an external site see downloads on external site (opens in new window/tab) for mor information

It is worth noting that the title of a Download and the name of the downloadable file are not the same item and, in principle, are not related; they could be totally different.

Actually a Download has two language related items.  One, which is the multilingual item, is called the 'Download Language' (in some places it might just be 'Language').  The other falls into the class of additional information and is called the 'Language for the downloadable file'.  This does not necessarily relate to anything multilingual but could refer, for example, to the programming language of the file.  It is the Download Language that is used with Associations. Usually the structure of a Download is the same in each language.  The exact content will obviously change, most obviously the Title of the Download will be in a different language.  Items such as the symbol, the licence, the creator and so on will often be the same for all the associated Downloads.  Sometimes the only difference between a Download in one language and its associated Download in another language might be the title, alias and the description.

Clearly a Download will be created in one language initially.  To ensure that the corresponding Downloads in the other languages are similarly structured then using the Multilingual Create/Edit method may be more useful.

Change Language with Batch

Note the Batch facility is also very useful for changing the language of the Categories and all the Downloads in a category and its subcategories.  It may be used to just change the language as well as making a copy of one or more Downloads.
In the example opposite there are three French Categories but the Language setting is All. 

So select all of them and then click on the batch button  button. 

This brings up the Batch facility so use the Set Language pull down to select the target language.



Having set the language ensure that No is selected in the 'Do you want to move' - No is the default.

Then click on Process button.






The result is shown opposite with all the relevant categories set to French.


batch21batch23batch24batch25
The same batch mechanism may also be used for the Downloads.  Here it is simple to use the Search tool to select the relevant top level category as that will also list all the Downloads in the sub categories so you can select them all.

For more information see batch processing (opens in a new widow/tab).

Layout Place holder


The jDownloads 3.9 Download and Download Details layouts have a placeholder {show_association} which generates a text such as shown opposite.


If, for example, you click on the French flag,assoc flag de, then the view switches to the associated French Download Detail view.
layout01 layout01A

Multi Language Associations

The key to a successful multilingual site are Associations.  When constructing such a site then each language has a 'language specific version' of each Category and each Download.  The principle aspect of an Association is that it lets the system know items are 'joined' so that if you switch between languages then the relevant associated item is shown.

In this article a four language site with Arabic, English, French and German items is used for demonstration examples.  So there will be "flags" like lang field00. Typically if the flags are at the top right of the view then clicking on one of them will switch the entire site to the selected language;  or if they appear in the Download then clicking will change to the associated Download.

Creating Associations

In the following we show two methods of associating Categories and associating Downloads.

One method is to use the Control Panel Categories assoc cats or Downloads assoc downloads entries on as appropriate.
The other method is to use the Multilingual Associations assoc multi entry.  This second method may be preferred for Downloads as it allows side by side editing.

In this article to hopefully make thing clearer, Categories have titles of the style "Test Cat-XX" where the XX indicates the language of the category.  Thus the top level categories are Test Cat-AR, Test Cat-EN, Test Cat-FR and Test Cat-DE.  Download titles have a similar convention.
Note: This is not a requirement, it is just an attempt to simplify the explanation!



Each of these top level categories has two subcategories, one called 'pdf files-XX' and the other called 'zip files-XX'.

The pdf-files-en sub categories are illustrated opposite.

associations 02

Using assoc cats or assoc downloads


Selecting assoc cats in the Control panel and then selecting the relevant language in the Search Tools gives a view such as shown opposite

associations 02

Clicking on the name of one of the categories,  say 'pdf files-EN' for example, and then selecting the Associations tab shows the other languages.

associations 03

After clicking on the Select button for one of these languages, German say,  a list of available categories with that language setting will be shown.

Next click on the name of the category that is to be "associated" with the original category, in this example 'pdf files-DE'. 


associations 04

This will then go back to the Associations tab which now looks as shown on the right.
associations 04A

After repeating for all the languages then  click on Save & Close which returns to the list of categories. 

associations 06
This shows that the associations have been set.  Also it is sometimes useful to choose a different Category symbol for each language.

If you hover the mouse over an association it shows the name of the associated item.associations 07
The sequence for associating Downloads is similar except of course it starts with assoc downloads in the control panel.

Using assoc multi

In many instances it is much simpler to use the Multilingual Association entry in the Control Panel as it also offers Create/Edit facilities

Clicking on the control panel 01A button   will show the current status of the Associations for either Categories or Downloads in the selected language.

control panel 02
In this example all the associations for the categories for each the languages were established using the first method as described above.

Using the pull downs at the top left select Downloads and the language.

Note that no Downloads have Associations established yet. 

Clicking on a Download title opens the Multilingual editing screen as shown below.

control panel 03


Initially the righthand side of the screen will be empty.

First use the Language pulldowncontrol panel 05A to choose which language.
control panel 06

At this time there is no associated Download so the 'Create a Download' view is shown.

If a Download had already been associated in the selected language then the 'Edit' view would be shown.

assoc19

But note the Select Target button, so click on it.

This gives a list of all the Downloads in the specified language.

Click on the title of the Download that is to become associated with the Reference Download.

assoc20

This returns to the Reference and Target 'double page' view.

Ensure you click on the Save Target button and then Close.

If you do not Save the Target then all the effort is lost!



assoc21
After closing the 'double page', the Multilingual Associations view is shown.  This now shows that, in this example, the English and German Downloads have been 'associated'.

assoc22

Using Batch to create other language Categories and Downloads

The Downloads Batch facility may be used in three ways:
  1. to Move multiple Downloads from the present Category to another Category and set the language, access or tags of the moved Downloads ;
  2. to Copy multiple Downloads from the present Category to another Category and set the language, access or tags of the copied Downloads;
  3. to just set the language, access or tags of multiple Downloads
So having made one or more Downloads in one language then it is the Copy function that is most useful to get them copied over to the associated category. 
  1. When you COPY a Download only the Download is duplicated; no downloadable file is duplicated.
  2. If COPY is selected then any other selected actions are applied to the copied item but not to the original item.
  3. Preview Files and Images used in Downloads are held in a 'central' location with database entries indicating their location so those links are copied.

Existing Multilingual Sites

There is also a Batch function in Categories  so if you have set up the initial top level multilingual specific categories and say a set of subcategories in one language then you can copy over all the sub categories from that language to another top level language category, changing the language setting in the copy process.  Generally this means just going to the 'new' subcategories and changing their names and alias to the the actual language.

From the Downloads screen in the backend select (tick) the Downloads that you wish to copy to another Category then click on the Batch button.

This will bring up the batch function window.  Set the required language and target category  and click Process.

 batch 10A
In the example this was repeated for the German language.
The example Downloads were renamed to match the language and the Associations set up as described above.

Remember that the downloadable files themselves will not have been copied.

 batch 13
So if you look at the Downloads listing, such as the one shown opposite, then you will find that the 'copied ' Downloads have no downloadable file as indicated by the red symbolbatch 16.

If you click on the name of one of the files and select the Files Data tab you may either select a new file or select a file from another Download.   This facility is available in the Front End as well as the Backend.

 
batch 14
In this instance using a file from another Download was selected. The Other Download selected was of course 'Existing Logos' as the downloadable file is just a pdf with a set of car logo images.

After being selected and returning to the list of Downloads the result is shown opposite.

The file icon is now orange in colour to denote the downloadable file is in another Download.

 batch 15
Hovering the mouse over the orange symbol, orange, gives the Category and file name of the actual downloadable file. Obviously this is repeated for the other language.

Converting to Multilingual

If you have an existing site which you need to convert to a multilingual site then after following the multilingual setup you will no doubt be left with many jD categories and Downloads that have the Language set to All.  With more than say a dozen entries, it would be extremely time consuming to go through each and every category and Download to change to what one might refer to as the 'original' language.

Using the Batch facilities simplifies the whole language changeover process.  The site can be up and running with an explanatory note about the changeover being carried out. The translations and adding downloadable files are readily carried out from the front end.

Other Text in jDownloads views

There are various places in the Options where ancillary text may be used.  For example in Options - Front End tab there are setting for 'Component Description' and 'Footer Text'.  If you use AUP in the Specials tab then the message to the user would benefit from being made language sensitive.  Another possibility is making the email subject language sensitive in the E-Mail tab.

In User Groups Settings - Limits tab there are multiple places where making the message to the user language sensitive would be most useful.  Also in User Groups settings -Group Settings tab the Waiting Time Message would be better as language sensitive.

To make these items Language sensitive jDownloads supports language 'plugin' tags such as {en-GB}...{/en-GB}  for English. 

To determine the language tag for a language  go to Extension Manager -Language(s). This will show the list of languages installed in Joomla and the relevant language tag.
other text 02
You also need to install the corresponding jDownloads language pack as described below. Installing a language pack for a component does NOT use the Extension Manager - Languages.

As an example let us modify the  Component Description in Options- Front End tab so that it looks as shown opposite.  Note that the text may also contain HTML. other text 01

The result for each language is shown opposite
other text en01 other text de01 other text fr01

Brief Note on Installing jDownloads Language Packs

To install another language in jDownloads use the regular Extension Manager - Install as if you were installing any extension.

Do NOT use the Install Languages tab
.
Now browse for the file then Upload & Install

For a more detailed explanation see Install a jDownloads Language Pack. (opens in a new window/tab)
Install-Lang02A
Note It is essential that the normal Joomla! language package has already been installed first.
That is in this example the French language for Joomla! must already be installed. No warning is given if it has not been installed!

Typically you will then see a message such as opposite.  You now have the jDownloads Language installed.
Install-Lang02B

Appendix: Converting an Existing Site to Multilingual

These notes are based on a response by nizz0k in StackExchange

The process will require a number of steps. It is much less tedious to plan a multi-language site from the beginning, than to implement another language later. I recommend getting translations for your content in advance. These are the steps I went through to get satisfactory results.

  1. Install the desired Joomla! languages through Extensions -> Languages.
  2. Configure and add your Content Languages in the Languages Menu.
  3. Enable the Language Filter Plugin. Optionally add and enable the Language Code module for better SEO.
  4. Create Language Content categories and recreate your existing categories for each language.
  5. Rebuild your menus. This is probably the most involved step because you will have to recreate your Main Menu in your "Main" language and then rebuild those menus for the additional language(s) you want to add. I found that using "Saves as a Copy" was really helpful in duplicating the pages. Remember to assign menu specific home pages and associating each page with its translation. To finalize the process you will have to add modules to each menu in the menu manager.
  6. Translate/Add/Remap your content. You will need translations of every piece of content you want to display. Then you need to add the content, label it with the appropriate language, and associate it with the "Main language" versions. This will include creating new Language categories and subcategories. I also had to save copies and re-label a number of my modules to maintain language consistency. This also meant applying translations to a number of Custom HTML modules, and a few of my own modules.
  7. Add the Language Switcher Module.
  8. Iteratively check the site for consistency. As an FYI, any pages that don't show up in the menu it is probablybecause they not categorized in the correct language.

Colin Mercer June 2019, Modified July 2021

Tags: index

Print Email