Joomfish UserGuide

2006 Think Network, Munich www.joomfish.
net
2006 Ivo Apostolov www.thinklabs.net
Joom!Fish Project ivo@joomla-bg.com

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
ivo@joomla-bg.com
http://www.joomfish.net
http://www.joomla-bg.com

2006 Think Network, Munich www.joomfish.net
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 didnt fork the component, but just
renamed it.

Q: I saw a version of Mambelfish 1.5.2, but it doesnt 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 doesnt 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 doesnt work together with Joom!Fish. We expect this to
be fixed with new versions of those components, as it really doesnt 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 dont have some of them, this means that your system doesnt 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). Dont worry, this will not remove your current translations.


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.

DONT 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.

Dont 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_f
ish_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_elemen
ts
If you dont 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.

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.mo
d_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:


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
ivo@joomla-bg.com. 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.

Joomfish UserGuide

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Joomfish UserGuide

Uploaded by

Copyright:

Available Formats

2006 Think Network, Munich www.joomfish.

You might also like