

M17n MANAGEMENT & CONFIGURATION
----------------------------------

Basic Approach

 The common approch is to have all Multilingual menus in
 you mainmenu and then to pick a language for each item.
 Then, you should define which submenus will be attached
 to the main menu items, which allows you keeping all of
 the multilingual feature at one level and manage your
 submenus independently. This is the simpliest approach
 and probably the most efficient as you will only deal
 with multilingual menus on the first navigation level.
 

 For advanced multilingual features, association keys
 are available but must be set individually for each
 menus. Initially, the language selector was taking
 users to the homepage upon switching the language but
 now associative keys (M17n keys) allows you to define
 on which page to send a user from each page. Still, if
 you are not familiar with, you may disable association
 handling from the plugin and enable it once you feel
 more confortable with M17n features.

 Still, as this simple package does not handles "full"
 multilingualization into Joomla, features such as the
 front page items are not multilingual. To bypass this
 frontpage mechanism, we suggest you to use sections &
 categories instead. This might seem tricky but is, so
 far, the simpliest solution available and the easiest
 to understand for beginners AND for advanced users.

 Below are described the steps to manage and configure
 the different M17n package elements.


Languages

 To manage your languages, you will have to use Joomla's
 language manager under:

 	Administrator > Extensions > Language Manager

 You can find dozens of languages available on Joomla's
 website but pay attention to the version, as some have
 not been yet ported for Joomla 1.5 Stable.

 The language selector and the menus managment will only
 propose you the languages that are installed.


Menu Items

 Now, you can select a menu from the menu manager:

	Administrator > Menus > Main Menu (or any other)

 Look at the top-right corner of your menu items list
 and notice the new added drop down menu for filtering
 contents by language. Universal means "NOT SET YET"
 or more simply, an item that will be shown no matter
 what language the user selects.

 Click on an item and look on the right side parameters.
 Expand "> M17n Parameters", described below:

	Language: 	The targeted language (a list of
			the currently installed langs)

	SubMenu:  	Child menu for item (optional)
			The current item will "hilight"
			when any item of the selected
			child menu is open.

	User Access:	Coma separated values (optional)
			Only shows item to those users
			that are in this list. If left
			blank, then shows to all users.

	Assoc. Key:	This allows you to associate a
			menu item with another to have
			"replicated" sites and so you
			can stay on the same page when
			switching the language. Please
			see the plugin details for a
			more detailed description of
			this feature.


Module (Language Selector)

 Now, you can select a menu from the menu manager:

	Administrator > Menus > Main Menu (or any other)

 Pick an item and look on the right side parameters.
 Expand "> M17n Parameters", described below:

	Sel. Prefix: 	A text to display before the
			languages in the module.

	Sel. Suffix: 	A text to display before the
			languages in the module.

	Style:  	CSS style options for the lang.
			selector items.


	Lang. Label: 	
	Define how to display each language on the
	selector. Full text by default.

		Full Text, as defined in the language
		xml file. E.g. English (United Kingdom)

		Short Text, simplified version of the
		previous, as defined in the language
		xml file but without the text that is
		between parenthesis. E.g. English

		ISO Code, as defined by ISO 639-1, a
		two letters abreviation. Taken from the
		locale code in the xml file. E.g. EN

		Icons, uses images instead of text. The
		default icons are located in :
		/PathToJoomla/modules/mod_M17n/icons/

	Icons Folder: 	Change this if you want to use
			your own icons. Not all of them
			are necessary but you MUST use
			the same naming convention.


	Active Language:
	This defines how to display the language that is
	currently in use. Default is to disable link on
	the current language.

		No link on current, this disables the
		link (href) for the language in use.

		Hide current language, the language in
		use will not be displayed at all.

		Background Hilight Color, this will
		display a background color behind the
		selected language. May not be visible
		when using icons, depending on CSS.
		Set the color on the next option.

		Border Hilight Color, this will
		display a one pixel border around the
		selected language. Set the color on 
		the next option.

		No hilight, all languages are shown
		identically. Unrecommended because it
		is is confusing for the end-user as
		no difference is made between each of
		the languages available. Initially,
		the module worked this way.

	Hilight Color:	Allows you to specify which
			color to use when the previous
			option is set to background or
			border highlight. You can use
			an hexadecimal color code (like
			#ff0 or #FFFF00) or you could
			also use CSS color names (such
			as grey, black, blue, green)


	Separator:
	This defines how to separate each language in
	the language selector module. Default option
	is carriage return (<br />).

		Carriage Return, this separates all of
		the choices with a <br /> tag.

		Simple Space, will simply display a
		single space between choices (&nbsp;)

		Wide Space. this will show a "triple"
		space between choices ( &nbsp; x 3 )

		Custom Spacer, allows you to specify
		your own separator string in the next
		text field (Custom Separator).

	Custom Sep.:	A string made of any html tags
			or characters. If you decide to
			use &nbsp; it seems to work but
			when you come back to edit the
			module again, the &nbsp; may
			become a question mark (?). You
			will have to replace every time
			you want to edit the module.


	Howlong to remember:
	This defines howlong the language choice shall
	be remembered by the module. Default option
	is to store it in the session.

		Session Lifetime, will store the value
		in the session, user will have to set
		it everytime the site is visited.

		Permanent, will store the value in a
		cookie with a one year lifetime.

		Custom Lapse, will store the value in
		a cookie but using a custom lifetime
		as defined on the next field

	Custom Lapse:	The number of days that cookie
			lifetime should last. This will
			only be used when the previous
			option is set to Custom Lapse.


Plugin

 The plugin allows the whole site to know which language
 the end-user has currently selected and which ones are
 available from the current page, depending on the
 choosen configuration. Please go to:

	Administrator > Extensions > Plugin Manager

 Usually, the M17n plugin is located on the second page,
 but it depends on how many plugins you have installed.
 Search for and click on:

	System - Multilingual (M17n)

 On the right side, you'll find the parameters.
 Under "Plugin Parameters" you will find:

	Association Handling: 	
	This option defines how the associative keys
	will be handled. Those keys are used to match
	a specific menu item (e.g. Products in english)
	with the corresponding menu in another language
	(e.g. Produits in french).

		Automatic, if assoc. key is found it
		will be used. Otherwise, home item will
		be used instead. Default Option.

		Strict, only assoc. keys are used. If
		no association key is found, then the
		language selector will not display the
		other languages.

		Disabled, only home items will be used.

	Home Items Retrieval: 	
	The home items are the default Itemids for each
	language. Depending on the association handling
	type, Itemids may not be used.

		Automatic, this will seek for the first
		menu item for each language and define
		it as the "Home" Itemid. The search is
		using the order position in the menu.

		Manual, that option allows you to set
		the Home itemid manually for EACH of
		the languages installed. We strongly
		recommend to use a different value for
		each language if set to manual. The
		Manual Home Items below must be set.

	Manual Home Items: 	
	This field is to be used when the previous
	option has the Manual value selected. Values
	in this field should contain all languages
	that are installed, separated by comas:
		en-GB=1,de-DE=11,fr-FR=21
	This field will need update when a new lang.
	is installed on the website. Please check on
	the language file XML to see what locale is
	to be used (en-GB, en-US, fr-CH and so on)
	
 
Notes:

 Voil, this is not the most smart or reasonable way to
 implenment M17n on Joomla but as this may be a future
 feature in 2.0, we thought this could be usefull for
 those out there willing to setup a multilingual site
 in the meanwhile. 

 Please note that this is our first official contrib on
 Joomla. Previous version were available for RC2, RC3
 and RC4 and can be provided if required. If any new
 release of joomla comes out, we will check it against
 the current version to ensure compatibility follow up
 and to make sure the package still works.