Multilanguage solution for Joomla!

© 2006 Think Network, Munich www.joomfish.net © 2006 Ivo Apostolov www.thinklabs.net Joom!Fish Project [email protected]

The first breath of the Fish, the dinner menu, what is it about?

How to start? Does the fish speak Japanese? Or just …

Multilanguage solution for Joomla!

www.joomfish.net

The ultimate guide for Joom!Fish Author: Ivo Apostolov

[email protected] http://www.joomfish.net

http://www.joomla-bg.com

http://www.joomfish.net

http://www.thinklabs.net

mailto:[email protected]




http://www.joomla-bg.com


Contents: 1. What is Joom!Fish? 2. What is not Joom!Fish? 3. Requirements 4. FAQs 5. Current issues 6. Installation 7. Tuning 8. Translation process 9. How to translate external extensions 10. Templates tricks and tips 11. Other Tips and Tricks 12. Upgrade (Migration from Mambelfish) 13. Support Us





1. What is Joom!Fish? Joom!Fish is an extension of Joomla! which allows you to create web sites, which has more then one language version. This is the extension main purpose and probably it could be used in a different ways, but keep in mind, that it was not designed for anything, except the described above. Joom!Fish allows you to maintain and organize your manually translated content in your Joomla! database. The Joom!Fish is a facility that gives you the chance to build Multilanguage sites by using ONLY ONE installation of Joomla! The key features of the application are:

• Possibility for an unlimited amount of languages • Possibility to MANUALLY translate all dynamic content of your Joomla! installation in ONE

database • Overview of the changed contents in the Translation list • Support for all the core components/modules of Joomla! • Front-end extension for language selection • Supports MOST of the 3PD extensions

2. What is NOT Joom!Fish? The Joom!Fish IS NOT AN AUTOMATIC translation tool, it allows you to create sites with Multilanguage versions, but the whole translation MUST BE DONE BY YOU. The Joom!Fish is NOT a tool that will do any translations for you, it allows you to build Multilanguage sites, but actually the whole process should be performed by at least a publisher (depending on the component configuration). Joom!Fish is not supposed to work on Mambo. It was not designed, tested or planned to work on it. Anyway feel free to use it, if you are able to debug it. Joom!Fish is not a stand-alone application. It is not useful, without running Joomla!





3. Requirements Joom!Fish 1.7 requires Joomla! 1.0.7 or above (Current and recommended is 1.0.10) and write access to the following directories:

• mambots/system • mambots/search • modules/ • components/ • administrator/components • includes/js/ThemesOffice

4. FAQs Q: Is the Joom!Fish a fork of Mambelfish? A: No, the Joom!Fish is created and developed by Alex Kempkens and a small team. Alex Kempkens is the original developer of Mambelfish, so he didn’t fork the component, but just renamed it. Q: I saw a version of Mambelfish 1.5.2, but it doesn’t works for me? A: For a short term, there was a version named 1.5.2 of Mambelfish, but it was not developed by the Joom!Fish team, neither from Alex Kempkens as well. There are plenty of modifications, patches, forks and hacks of the Mambelfish, but the latest version released under this name is 1.5. If you need support for other versions, patches, forks or hacks of the Mambelfish, please refer to the person who provided the code. Q: Is Joom!Fish supporting Japanese? A: Yes, basically Joom!Fish is expected to support ANY language, it doesn’t matter if it is Japanese, Bulgarian or Swahili. Q: Is Joom!Fish released under GNU/GPL? A: No, it is not. Joom!Fish is released under Open Source License, but it is not GPL. Please read carefully the license in the documentation folder of the package. Q: Am I able to create a site with more than two languages? A: Yes, it is expected that you will be able to create sites with as many languages you want. Joom!Fish is MULTILANGUAGE content manager and is NOT just bilanguage content manager!





Q: Who is the author of the Joom!Fish? A: There is a team behind the Joom!Fish consisted by: Alex Kempkens (Main Developer and Project Leader), Geraint Edwards, Levis Bisson, Robin Muilwijk, Jim De La Hunt and Ivo Apostolov. Joom!Fish is an OFFICIAL Joomla! extension. Q: I want to support you. How can I do that? A: You can support either the Joomla! Project by donating on http://www.joomla.org/content/view/689/79/ or you can specifically support the Joom!Fish project by purchasing a nice product from our on-line shop on http://thinklabs.net/external/joomfish_shop.html 5. Current issues The current issues known are: A) Some advanced SEF components doesn’t work together with Joom!Fish. We expect this to

be fixed with new versions of those components, as it really doesn’t depends on the Joom!Fish team to fix those issues.

B) The sections names on the frontpage are not being translated, if the menu link has this parameter ON. This is expected to be fixed in Joomla! 1.0.11 (if there is such). Temporary solution can be found at: http://forum.joomla.org/index.php/topic,80065.0.html

6. Installation Make sure, that your system covers the requirements from point 3 and download the latest Joom!Fish version from www.joomfish.net and install the ZIP file as a component. That is all. You are done. Before continue, make sure that you have:

• Component Joom!Fish in the administrator-> Components • Module Joom!Fish in the site modules list • Mambot (or Plug-in) for Multilanguage Search Support • Mambot (or Plug-in) for initialization of the Joom!Fish Multilanguage support

If you don’t have some of them, this means that your system doesn’t cover some of the requirements described in point 4. If you receive an error message: Another component is already using directory: "W:\www\joomla\components\com_joomfish\"

that means, that there was already a installation of the Joom!Fish, that should be removed (uninstalled). Don’t worry, this will not remove your current translations.




http://www.joomla.org/content/view/689/79/

http://thinklabs.net/external/joomfish_shop.html

http://forum.joomla.org/index.php/topic,80065.0.html



If you are upgrading from Mambelfish, just install the Joom!Fish as described above and run the component. There is an upgrade option, and by just following the instructions you will switch your Mambelfish to Joom!Fish. DON’T FORGET TO MAKE A BACKUP BEFORE UPGRADING. After the upgrade, you must remove all bots, modules of Mambelfish. 7. Tuning There are several options that you can tune before starting the translation process. From the component settings, you would be able to choose the language of the component (the language used in the admin panel only), who is able to post translations from the frontend and what to be showed if there is no translation. NOTE: If there is no translation at all, the option to choose what to be showed if there is no translation will be ignored. From the module settings, you can choose whatever to use the module stylesheet or not, to choose the position of the module, to use specific class from the Joomla! stylesheet for the module, to show or not the active language, what spacer to be used between the language names, how the language switch option to be showed. You can also enable or disable the cache for the module. You can set up some options in the bots as well. - The system bot allows you to choose if the language determination should be used and how

the site should appear after it is loaded. - The content searchbot has an option to choose if it should search in the non-linked static

content and what should be the search limit. You can choose which languages to be active on the sites from the Languages option of the component. Note that in order to appear there, the language should be installed first. Note also that there should be an ISO code for the languages in use.





8. Translation Process To translate the content use the translate option of the component, first choose a language on which you are going to do the translation and after that the type of the element you want to translate. A list of all available items for translation will appear and by clicking to one of them, you will be able to edit the translation or create a new one. Don’t forget to publish the translation, in order to appear to the frontend correctly. 9. How to translate external extensions? In order to translate external translations, you need the so called Content Elements files for each extension to be putted in the administrator/components/com_joomfish/contentelements folder. This XML files, are usually provided by the developers of those extensions or some other developers. Note, that the Joom!Fish team is not responsible in providing such files. The content element files include information about the database structure and what and how should be translated. Easy way to add such Content Element files is the Joom!Fish Content Element Installer component. It can be downloaded from: http://forge.joomla.org/sf/frs/do/downloadFile/projects.joomfish/frs.joom_fish_addons.joom_fish_content_element_instal/frs6509?dl=1 Content Elements for some of the most common extensions can be found at: http://forge.joomla.org/sf/frs/do/listReleases/projects.joomfish/frs.3rd_party_content_elements If you don’t find the necessary content element files, please ask the developer of the extension or search in the forums. NOTE: In order to run correctly the extension MUST have all of the used languages in its language folder. Example: If you use EstateAgent, and you run a site in Bulgarian, English, Dutch and German, you need to have the files bulgarian.php, english.php, dutch.php and german.php in the language folder of EstateAgent.




http://forge.joomla.org/sf/frs/do/downloadFile/projects.joomfish/frs.joom_fish_addons.joom_f

http://forge.joomla.org/sf/frs/do/listReleases/projects.joomfish/frs.3rd_party_content_elemen


10. Template tricks and tips

a) Different templates for different languages – To create different templates for the different languages, you can use various tricks in calling the template or calling different CSS files. The easy thing is to use the same template but for example different colors. This could be done by using the following code for calling the CSS file:

So

Now,

Joomla! will search for a CSS file named languageinuse.template_css.css And if you run a site with French, German and English you need to have the following files in your template CSS folder:

• french.template_css.css • german.template_css.css • english.template_css.css

You can now determine what to show by entering different CSS code in each of the files. If you want to create a web site with totally different templates, you need to call the template by using PHP and if conditions. The logic is that you have a default template, already defined in the database. In the index.php file of this template, you need to set the conditions.

<link href="<?php echo $mosConfig_live_site;?>/templates/<?php echo $mainframe->getTemplate(); ?>/css/<?php echo $mosConfig_lang;?>.template_css.css" rel="stylesheet" type="text/css" />





There is alternative way to create a “fake” template, where based on the language different template is loaded. This is similar to the method described above, except that the index.php file of the default template will not include any code, but just a determination of the language and will call a template related to that language. Such template can be found in the ZIP file bellow:

Multi.zip





b) How to change the site name in a Multilanguage site – This is a hard thing to do, and there might be better way, but the easiest one is to put the following code before anything else in the head tag: Now you have to add the same definition to the language files used in your site. So if you use English, German and French you need to add it to all of the three files. The code will be: c) How to make different menus in the different languages (Please note, that this is not related to the translation of the menus, but for the cases, when you want to have different menus for the different language versions of your web site) – You can add a function before the load of the module position, where the clause will be logically: If the current language is XXX, then load module position Y. This is a simple way to make some module to appear only in some languages. Example: So if you now create two menus, the first you want to appear in the English version only and the other to the German only, you put the menu for the English version on module position user5 and the German on position user6.

<title><?php echo _SITE_TITLE; ?></title>

DEFINE('_SITE_TITLE','Site Title');

<?php if( $mosConfig_lang != "english" ) { ?> <?php mosLoadModules( 'user5' ); ?> <?php } ?> <?php if( $mosConfig_lang != "german" ) { ?> <?php mosLoadModules( 'user6' ); ?> <?php } ?>





11. Other tips and tricks

a) How to use language dependent menu items / menus?

The basic thing behind this issue has nothing to do with the Joom!Fish in special. However this topic is of course connected. There are some basic things you need to understand prior some solutions can be explained.

Technical / Organizational background of the Joom!Fish

The translation engine of the Joom!Fish provides an effective and generic way of translating everything in your database. This means on the other side that this engine does not know about logical structures or relationships within you tables.

If you show a list, e.g. of menu items, and technically you select the rows of your table. The number of rows will not be changed by the Joom!Fish. Meaning independent if there is a translation available or not all menu items you are allowed to see will be shown.

Even more, as the menu items do not have any idea of how many content items resist behind their links, there is no change for the Menu or Joom!Fish to remove menu links with a section/category that is not providing content.

If you look at the content lists it's getting more logical. If you browse a section you see a list of categories including a number of items which are available in this category. This number is generate by a select count to the content table. This select count does not provide any information the Joom!Fish could use to check if this number is valid or not as the result is just a number. So if the Joom!Fish would later show less items than the count provides it would mess up everything in your site.

So what's a solution?

The most simple solution is a "language aware menu module".

The trick is simple but effective. If you provide your system with more than one menu (Administrator -> Menu -> Menu Manager) such as:

• mainmenu • mainmenu_en • mainmenu_fr





Then you could enhance your menu module in the way that it is using the language depended menu instead of the normal one. In our case the mainmenu would refer to the default site language (e.g. German). The other menu's would refer to language depended menus.

As the linking of menu's to sections, categories ... results in different ItemID's you can even organize different set of templates, modules and other extensions within the language depended part's of your site.

Ok this solution is not an automatic one, but it gives you a lot of flexibility and possibilities.

One example

We have implemented a multilingual aware mod_mainmenu for Joomla! 1.0.x. You can download it on: http://forge.joomla.org/sf/frs/do/downloadFile/projects.joomfish/frs.joom_fish_addons.mod_mainmenu/frs5238?dl=1

b) How to use language dependent images?

Using language depended images refers to two different sections:

• Images within content • Images or styles within the template

A related topic is the use of different styles or layouts in a template. It is generally advised to use different directories for the different language related images or styles.

Images within content

To change the images within the translated content you can use the additional image files. The translatable fields are not handled like in the standard content dialog, but you can easily copy the original values and change the name of the image in the text field.

Images or styles within the template

The easiest way to handle this issue is to make the template aware of the posiible languages. This can be handled by adding either a reference to $mosConfig_lang or $iso_client_lang to the template image code or style sheet.

Within a template this can look like:




http://forge.joomla.org/sf/frs/do/downloadFile/projects.joomfish/frs.joom_fish_addons.mo


This code loads the language depended Style Sheet as long a file like template_german_css.css exists.

You can do something similar with your image tags, here it is advised to use different directories such as:

There is also another simple way, if the files are put in the template. Name them for example: english.header.jpg, bulgarian.header.jpg etc. Then call them from the template by using the following illustrative code:

<?php $template = 'template_css.css'; $langTemplate = 'template_' .$GLOBALS['mosConfig_lang']. '_css.css'; if( files_exists( $mosConfig_live_site .'/templates/rhuk_solarflare_ii/css/' . $langTemplate ) ) { $template = $langTemplate; } ?> <link href="<?php echo $mosConfig_live_site;?>/templates/rhuk_solarflare_ii/css/<?php echo $template;?>" rel="stylesheet" type="text/css" />

<?php $imageDir = $mosConfig_live_site . '/templates/rhuk_solarflare_ii/images'; $langImageDir = '/' . $GLOBALS['mosConfig_lang']; if( dir_exists( $imageDir . $langImageDir ) ) { $imageDir = $imageDir . $langImageDir; } ?> <img src="<?php echo $imageDir;?>/myimage.png">

<img src=”<?php echo $mosConfig_live_site; ?>/templates/<?php echo $mosConfig_cur_template; ?>/images/<?php echo $mosConfig_lang; ?>.header.jpg”





c) Encoding

The term Encoding refers to a relation between character codes and characters. It is also known as charset or character set. The ISO8859 standard defines a series of encodings for European languages, e.g. ISO 8859-1 to represent Western European languages like English, French, and German.

Q: Does the template need any special head tags to work properly with the Fish?

A: Actually yes. The fish is getting the charset from the language file of the LANGUAGE IN USE. So that means, if you set a hard-coded charset in your template, you will most probably have problems with other languages (encodings). You can use the following tag in order to be sure that the page will be loaded with the proper encoding: <meta http-equiv="Content-Type" content="text/html; <?php echo _ISO; ?>" />

The name "_ISO" here refers to the current encoding specified by the language in use. The term has other meanings in other contexts in Joom!Fish and Joomla; see the ISO article for more information.

Q: Does the Fish differentiate the language through to specific charset?

A: Actually its exacly the oposite, the Fish differentiate the charset through to specific language.

Q: So, in other words, it is possible to use utf-8 for example for English and German, too?

A: If you use UTF-8 for all of the languages you use, there is no problem the charset to be hard-coded in the template

Q: How can I have language specific templates (e.g. a different template for RTL and LTR languages)?

A: One solutions is to create a dummy template index.php file that checks which language is being viewed (you could check the glabal variable $mosConfig_lang) and include the appropriate language dependent index.php template file. index.php would look like:

<?php global $mosConfig_lang; if ($mosConfig_lang=="language1") include_once("language1Template.php"); else if ($mosConfig_lang=="language2") include_once("language2Template.php"); ?>





d) Translating the date/time

If you want your Joomla! site to show a translated time and/or date when you switch languages, all you need to do is add a setLocale( <SERVER_ISO> ) into your language files.

For example, in a German language file you would add the code "setLocale( 'de' );"

12. Upgrade (Migrate from Mambelfish)

The upgrade assumes that you have a full running version of Joomla!. If you have implemented the Mambelfish or just use your old Mambo database is not that important. There will be only some steps which differ.

Please make sure to read thru the instructions PRIOR doing something.

1. Backup your System

Of course this is the first step as usual

2. Start from a clean Joomla! filebase

The following steps are based on the assumtion that you have done an upgrrade from e.g. Mambo to Joomla! already but not changed your Joomla! files yet. You can also achieve this if you remove all your changes you have done for the MambelFish integration into Joomla! - such as the index.php file.

May be this is a good moment to upgrade to the latest Joomla! filebase ;-).

3. Remove the MambelFish component

Before you actually start to uninstall the component please go into the file

$mosConfig_absolute_path/administrator/components/com_mambelfish/mambelfish.xml

Change the section of uninstall to look like this:

<uninstall> <queries /> </uninstall>





With this you will keep your tables in the database.

Now uninstall:

• MambelFish component • MambelFish searchbot

4. Install the Joom!Fish component

Make sure that your

• /mambots/system and • /includes/js/ThemeOffice

directories are writable for the server.

Use the standard procedure to install the component.

5. UTF-8 support

As a matter of fact the Joomla! 1.0.x series is not supprting UTF-8 be default. But it is possible to force the server to use it. In such a case you will have an MySQL with UTF-8 support enabled.

In this case it is required that you modify the collations of the text fields and of the table itself prior you run the migration, but after the install.

Please update the following tables

• <prefix>_jf_content • <prefix>_jf_tableinfo • <prefix>_languages

6. Run the migration

Go to Administrator -> Components -> Joom!Fish (Control Panel) and run the migration feature (in the table on the right side.

The function runs you thru a simple wizzard which allows you to backup your tables and make sure everything is ok. After the mirgration is done you get a screen give you a status overview. If everything is green you are done!

In case of an emergency





If you need to redo the migration you need to change the config value manually. Change in the file /administrator/com_joomfish/config.joomfish.php

the var to the value "0" again $joomfish_mbfupgradeDone = "0";

13. Support Us

You can support the project by purchase some of our really cool products from the on-line shop. You can choose a product from http://thinklabs.net/external/joomfish_shop.html Thank you for your support, and thank you for choosing Joom!Fish

The Joom!Fish Team This document or any parts of it can not be distributed, sold, copied without the explicit written agreement from Ivo Apostolov. It is distributed out of charge on the official web-site of the project – www.joomfish.net, anyway it is forbidden to be distributed through other web sites, without written permit. The Logo is made by Tommy White (www.tommywhite.com) and is the official logo of the Joom!Fish Project. If you want to translate and redistribute the document in your native language, you are allowed to do it, if you send a copy of it to [email protected]. The copyright of the translated document is YOURS, and you can distribute it at any FREE OF CHARGE, non commercial open source license. Distributing of translations under any kind of commercial license is prohibited.




http://thinklabs.net/external/joomfish_shop.html


http://www.tommywhite.com


Multilanguage solution for Joomla!

Documents

Transcript of Multilanguage solution for Joomla!