Actions

Help system/Translation and localisation

From Joomla! Documentation

< Help system
Revision as of 18:54, 24 February 2011 by Chris Davenport (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

The help system in Joomla 1.6 supports complete translation and localisation of all help screens. There are several ways in which this can be achieved and it is largely a matter of personal preference as to which method is selected.

If you want to set up a separate, probably public, help server for your localisation, then you should start by reading more about setting up your own help server. Alternatively, you might choose to have your localised help files served directly from your Joomla website.

The British English help screens for Joomla 1.6 are available for translators and others to use as a starting point under the Joomla Electronic Documentation Licence. Please read the license carefully, together with the associated FAQ if you would like to make use of the official help screens.

Scenario 1: Setting up a separate localised help server

In setting up a new help server it is a good idea to think about how the help screen URLs will be structured. For example, it is usually a good idea to include the Joomla version number as part of each URL because each Joomla version will require help screens specific to that version. If your help server is to support multiple languages then a language code will probably also need to be included in the URLs. For example, you could support multiple languages and multiple versions using a URL scheme like this

http://www.mydomain.com/en-GB/1.6/Content_Article_Manager
http://www.mydomain.com/en-GB/1.6/Content_Article_Manager_Edit
... etc. ...

http://www.mydomain.com/en-GB/1.7/Content_Article_Manager
http://www.mydomain.com/en-GB/1.7/Content_Article_Manager_Edit
... etc. ...

http://www.mydomain.com/de-DE/1.6/Content_Article_Manager
http://www.mydomain.com/de-DE/1.6/Content_Article_Manager_Edit
... etc. ...

http://www.mydomain.com/de-DE/1.7/Content_Article_Manager
http://www.mydomain.com/de-DE/1.7/Content_Article_Manager_Edit
... etc. ...

Assuming you have set up your help server as above then you will need to amend the helpsites XML file to allow users to access your help server. Add the following new <site> elements to the helpsites XML file, one for each language code that you are supporting on your help server.

<site
    tag="en-GB"
    url="http://www.mydomain.com/{language}/{major}.{minor}/{keyref}">
    English (GB) - Help screens
</site>        
<site
    tag="de-DE"
    url="http://www.mydomain.com/{language}/{major}.{minor}/{keyref}">
    English (GB) - Help screens
</site>

Notice how the elements enclosed in curly brackets are replaced by actual data for each help screen. These elements are referred to as substitution codes.

Since there is complete flexibility in how you structure the URLs you might consider putting each language in a separate sub-domain. For example, using a scheme like this:

http://{language}.mydomain.com/{major}.{minor}/{keyref}

Or perhaps you could have each language in a separate sub-domain, but split the region code into the path, like this:

http://{langcode}.mydomain.com/{langregion}/{major}.{minor}/{keyref}

It really is up to you how you structure URLs on your help server. The Joomla help system can support just about any conceivable scheme. Note also that, because of this flexibility, it is no longer necessary for the help server to be running Joomla; it could, for example, be running a wiki or even be just static HTML.

It is also possible to localise the help screen key references themselves, giving fully localised URLs. Help screen key references are passed through the Joomla language translation system before being substituted into the URL. For example, the Article Manager screen is associated with the key reference "JHELP_CONTENT_ARTICLE_MANAGER". This is actually a language key which is looked up in the currently loaded language files. In the case of British English the language file en-GB.ini contains the entry

JHELP_CONTENT_ARTICLE_MANAGER="Content_Article_Manager"

So the string "Content_Article_Manager" will be substituted into the URL as the key reference. If there is no key-value pair available for the given key then it will be used untranslated as the key reference.

Scenario 2: Using local help to serve localised help screens

If you don't want to go to the trouble of hosting help screens on a separate help server, then it is also possible to serve localised help screens directly from the Joomla installation itself.

To learn more about local help you should read Help system/Local help files.

Remember that the name of the file, with a ".html" or ".xml" extension, must match the translated key reference or the file will not be accessible from the Administrator help area.