Hi,
As most members would know, the definitive resource on this forum for information about creating multi-lingual sites using Couch is - viewtopic.php?f=8&t=74
That thread primarily discusses two distinct methods of implementing multi-lingual sites -
2. Using separate templates for each language
viewtopic.php?f=8&p=330#p330 (and also http://www.couchcms.com/forum/viewtopic.php?f=2&p=18935)
3. Using a single template but creating separate editable regions in it for each language
viewtopic.php?f=8&p=9010#p9010
Please note that I have numbered the methods above beginning with '2' - this is to maintain compatibility with the original thread where three methods are discussed and the two above are at the second and third position respectively (and are also repeatedly referred to by these numbers).
By far the consensus seems to be that, all things considered, the second method is the best. However it is complicated for the clients as they now have multiple templates to contend with. On the other hand, the third method is much simpler and easier for the client to work with but has some drawbacks that can prove to be deal-breakers in some cases.
Following quotes taken from our forum highlight those drawbacks
Actually, the reason for almost all the drawbacks mentioned above boils down to one single characteristic of the third method -
since the selected language is hidden as a 'session' variable, the URL of pages remain the same irrespective of which language is being displayed on them.
So, for example, a visitor goes to a page 'http://yoursite.com/products.php' and is shown contents in English. She clicks the language-switcher menu to select 'Portuguese' and the page refreshes to show contents in Portuguese. However, the URL of the page still shows 'http://yoursite.com/products.php' i.e. the *same* as English version.
Not difficult to see why this has negative implications for SEO and why caching would not work with this approach (both use URLs to differentiate between resources and here the same URL points to two different resources).
An effective fix for this problem would be to manifestly show the language of the contents in the URL e.g. -
Same links with prettyURLs -
Notice the 'en' and 'pt' in the links above.
And now since the different languages use distinct URLs, our problem would be resolved.
I am attaching a little addon here that does precisely that (and more).
This addon should also make the entire process of implementing the 'third' method ultra-simple as everything is neatly packaged in an addon (no 'switch.php', 'lang_switcher_menu.html' etc. required).
Some common requirements of a multi-lingual site are reflected in the following request by @JD -
This addon should make it a breeze to get those done.
So let us get going and see how that happens.
Installation:
Before we install this addon, please make sure your setup fulfills the following prerequisites -
1. Get the current version of Couch from GitHub (https://github.com/CouchCMS/CouchCMS). For this addon to work, it'll need at least "Couch v2.0 Build 20170710" (as of this post date, this is the latest version at GitHub).
2. If you'd be testing this addon on an existing Couch site and the site uses prettyURLs, please make sure to turn prettyURLs off (from couch/config.php) before installing this addon.
Don't worry, we'll turn those back on later (as explained at the end of this post). To begin with, we need normal URLs.
With the prerequisites in place, we can begin the installation.
The procedure remains the same as all the other addons.
a. Extract the attached zip to get a folder named 'multi-lang'.
b. Place this folder within the 'couch/addons' folder of your installation.
c. Finally, activate this addon by adding the following entry in 'couch/addons/kfunctions.php' file (if this file is not present at the specified location, rename the 'kfunctions.example.php' file there to 'kfunctions.php') -
Configuration:
Within the 'multi-lang' folder we placed above in the 'addons', you'll find a file named 'config.example.php'.
Rename it to 'config.php'. Open it in your favorite text editor and find the following setting in there -
As you can see, as a sample, it already has three languages configured for use on your site.
You are supposed to make changes to this setting to specify the languages your site will work with. Please note that for every language specified in it, you'll also need to specify its 'language-code' ('lc' as it will referred to in the rest of this discussion). You can see the 'lc' for the three languages above. For other languages, if you are unsure of its code, you may get it from the link shown above.
For the purpose of this discussion, I'll assume that we accept the sample configuration and make our site use the three languages specified above.
OK, with that done, we are ready to use this addon.
Visit any page of your site and observe its URL in the browser's address bar - you'll see that Couch automatically adds 'lc=en' to the URL.
e.g.
That 'en' is used because it, being the first language specified in config, is treated as the default language and so when no language is specified in the URL it gets automatically selected. You can, of course, set your desired language as the default by placing it first in the config array we saw above.
Let us quickly create a language switcher to test out the other languages we specified.
Creating the language switcher menu:
If we were to place a <cms:dump_all /> tag in any template, we'll see that this addon makes available to us some variables that can aid us in implementing a multi-lingual site.
Assuming that the page being visited is
http://localhost:8080/test.php?p=710&lc=en
and three languages have been specified (en, fr and pt) in config, we'll see the following new variables -
A brief description of the variables -
k_lang
This will always contain the currently selected language (you'll remember that this value is one of the language-codes we specified in the config).
k_link_en
k_link_fr
k_link_pt
These links point to the current page in all the available languages - notice the 'en', 'fr', 'pt' (our language-codes) appended to 'k_link_'.
In this case, the three links are for the three languages we specified in config. If there were more languages or other languages, the links would reflect those languages.
As you can see, these can be used to create a language-switcher e.g.
For quickly testing out the addon, you can use the menu above.
However, the next variable provides a more generic method of creating such language-switcher menus.
k_supported_langs
This is an 'array' (i.e. a compound variable) containing info about all the languages specified in config.
Try using it like this -
and it should output -
As you can see, the <cms:each> tag above iterates through all entries in 'k_supported_langs' and makes available each as two variables - 'lang' and 'lc'. These provide us with the names of all the specified languages and their codes.
We can then use those to create a generic language-switcher menu that will work across all configurations.
Here is a real-world example you may use as is or, as is more likely, use the technique in your own static design to convert an existing menu markup into a functional language switcher -
The code above outputs -
With proper styling, it looks like -
I'd like to draw your attention to two points above -
1. I renamed the images of flags I had, deliberately adding to each their respective language code (e.g. flag-en.jpg, flag-fr.jpg, flag-pt.jpg).
This way in the cms:each loop, I could use the <cms:show lc /> statement (outputting the language code) to show the flag belonging to the language being iterated.
2. More importantly, notice also how the flags are linked to their language versions of the *current* page.
So, if we place this menu in a snippet and make it display on all pages of our site, whatever page a visitor might be on, the flags will provide her with links to the *same* page in different languages.
Please notice how we are using <cms:get> coupled with <cms:show lc/> to output the values of 'k_link_en', 'k_link_fr' and 'k_link_pt' variables containing links of the current page in those languages -
As those familiar with the original "third method" (viewtopic.php?f=8&p=9010#p9010) will recall, the use of <cms:get> was pivotal in creating multi-lingual sites.
For those chancing upon this thread for the first time, please allow me a brief detour to explain the use of <cms:get> as this is used extensively further down (others may safely skip this section).
=================== begin detour ===============================
Please consider the following two statements -
Both will output exactly the same result (the English language link of the current page).
However, notice that the syntax of <cms:get> is different fron that of <cms:show> in that it requires "double-quotes" around the variable name - effectively this means that we are specifying a "string" as the variable.
This use of string opens up possibilities that are not available with <cms:show>. For example, consider this -
In the code above, notice we are using another variable (my_lang) *inside* the <cms:get> input string. The value contained in 'my_lang' is 'en', so after substitution, the final string that <cms:get> will receive would be "k_link_en" i.e. the English language link.
Now if we were to change the value of 'my_lang' to 'fr', the <cms:get> will fetch fetch the "k_link_fr" link instead.
Point is that we can dynamically change the output of <cms:get> by changing the value of the variable(s) used in its input string.
This makes it possible for us to code 'language agnostic' statements using variables that will change with the current language of the site, for example consider this -
The 'k_lang' variable, as you'll remember, will always contain the language-code of the currently selected language.
So, the statement above will automatically show the current page link in the language currently selected. If the current language is French, it will show the FR link. If the visitor switches over to English, it will automatically show the now current EN link.
It will work without any change everywhere without us needing to find out first as to which language is current and so which variable to show.
To illustrate the difference, following is the equivalent code using <cms:show> for our tri-lingual site -
The code above, apart from being more verbose, is also non-portable as you'll have to change it if you happen to add more languages to the site or change the existing ones.
That ends our detour (hopefully having established the usefulness of <cms:get>).
=================== end detour ===============================
Creating the main site
Once the language switcher is in place, try clicking the different languages and see how the URL in the browser's address bar automatically shows the selected language. So now each language has its own distinct URL for every page on the site.
We are finally set to show the actual contents in the selected language.
This part remains almost exactly the same as that deployed in the original method.
Of all the editable regions created in any template, some are common to all languages (usually the assets e.g. images, thumbnails, files etc.).
For the actual textual contents, we'll create separate editable regions for each language supported by our site.
So suppose a template originally requires only two regions - one image and the other textarea.
For a normal site (i.e. not multi-lingual), we could define the regions as follows
For our tri-lingual site, we'll define the regions as follows instead -
As can be seen, we have defined separate regions for the three languages. The important part is that we have appended the respective language-codes to the names of the different regions. This will make it easy for us to show the correct region matching the currently selected language.
Let us do that.
First input some data into the three editable regions in the admin-panel for testing.
Now at the place in your template where you need to show the content, use the following -
And that is it!
Switch between the languages and see how the content automatically changes to match the selected language.
By using this addon, that is all that you need to do for creating multi-lingual site -
1. Create editable regions with names containing the language-codes
2. Use <cms:get> to show the contents.
I think you'll agree, this addon makes the original method way easier to implement.
One last thing..
Ok, before we end the topic by turning on prettyURLs, there is one last point that I need to discuss.
As you must have realized, this new method banks upon the presence of the 'language-code' in *all* links present on any given page.
This is so that the visitor is always served pages only in the selected language. To illustrate the point, suppose a visitor selects 'pt' as her language. Now all the links on any page she visits should have 'pt' attached else she could land up on a different language thus breaking her context.
This addon tries to automatically add the language-code to most links on pages. I'd say, it succeeds in doing this for 95% of the links (notably all 'k_page_link' and links generated by <cms:link> tag). However, there are a few links which escape this treatment (primarily because making this addon manipulate those links would mean making sweeping changes to Couch's core).
I cannot provide an exhaustive list of variables containing such links but only a modest amount of testing applied to your fully implemented site should easily reveal those. One thing is certain about them though - all of them will definitely have the term 'link' in their names. So you can keep an eye on such variables while coding also.
For such links, this addon provides a tag named <cms:show_with_lc> that does the conversion for you.
The use is pretty easy. Take a look at the following -
The code above is some regular code involving pagination. Unfortunately, the 'k_paginate_link_prev' and 'k_paginate_link_next' are language-code unaware. To rectify that, we simply need to modify the '<cms:show >' part to '<cms:show_with_lc>' (i.e. 'show with language-code'). Our modified code becomes -
As you can see, it required a simple substitution at only two places.
[
For more complex pagination needs, do the same with 'k_crumb_link' variable. Please see -
viewtopic.php?f=4&t=10796
viewtopic.php?f=8&t=10168
]
Wrapping up
Once the site is complete and you are satisfied with the way things are working, the final thing to do should be turning on the prettyURLs (that is, if you do want to use those on the site).
Follow the standard way of doing this (http://docs.couchcms.com/concepts/pretty-urls.html) -
first edit couch/config.php to turn prettyURLs on. Then generate rewrite rules for putting into .htaccess file (the bottom of the sidebar in admin-panel now has a link for doing this). Copy and paste those rules into a .htaccess file and place that file in your site's root.
If your site was already using prettyURLs before activating this addon then you'll likely already have a .htaccess file you generated previously.
You'll still need to regenerate the rules and place them into the .htaccess file because this addon will add new rules of its own that have to be placed in the .htaccess file.
The last line is important - using prettyURLs with this multi-lingual addon expects a new set of rules in .htaccess file. So, in the future, if you happen to add a new language or modify the language-code of any existing language, you'll need to regenerate the rules and then update the .htaccess file with them.
With that done, access your site and take a look at the URLs it uses now. You should see something like -
Notice how this addon has added the language-codes *before* the template names so as to make it appear as if the templates were in subfolders named 'en/' and 'pt/' etc. So, in a way, the URLs now match those that we get using the 'second method' of creating multi-lingual sites.
That ends this post. Hope our members find this addon useful.
Please feel free to ask any questions you might have.
As most members would know, the definitive resource on this forum for information about creating multi-lingual sites using Couch is - viewtopic.php?f=8&t=74
That thread primarily discusses two distinct methods of implementing multi-lingual sites -
2. Using separate templates for each language
viewtopic.php?f=8&p=330#p330 (and also http://www.couchcms.com/forum/viewtopic.php?f=2&p=18935)
3. Using a single template but creating separate editable regions in it for each language
viewtopic.php?f=8&p=9010#p9010
Please note that I have numbered the methods above beginning with '2' - this is to maintain compatibility with the original thread where three methods are discussed and the two above are at the second and third position respectively (and are also repeatedly referred to by these numbers).
By far the consensus seems to be that, all things considered, the second method is the best. However it is complicated for the clients as they now have multiple templates to contend with. On the other hand, the third method is much simpler and easier for the client to work with but has some drawbacks that can prove to be deal-breakers in some cases.
Following quotes taken from our forum highlight those drawbacks
@Musman wrote:
About 'my_lang' based on session approach, everybody who use it should be awared of no-compatibility with 'cache' feature and with searching engines,
also may be problems with 'search' feature.. I've made a website using this approach, but will make another with folder approach, it's much more reliable.
@JD wrote:
Although I like the simplicity of dynamically loading the editable fields according to the set language cookie and managing all fields in one template,
I read some SEO sources that recommend against this approach as a page might not rank well.
Actually, the reason for almost all the drawbacks mentioned above boils down to one single characteristic of the third method -
since the selected language is hidden as a 'session' variable, the URL of pages remain the same irrespective of which language is being displayed on them.
So, for example, a visitor goes to a page 'http://yoursite.com/products.php' and is shown contents in English. She clicks the language-switcher menu to select 'Portuguese' and the page refreshes to show contents in Portuguese. However, the URL of the page still shows 'http://yoursite.com/products.php' i.e. the *same* as English version.
Not difficult to see why this has negative implications for SEO and why caching would not work with this approach (both use URLs to differentiate between resources and here the same URL points to two different resources).
An effective fix for this problem would be to manifestly show the language of the contents in the URL e.g. -
- Code: Select all
http://yoursite.com/products.php?lc=en
http://yoursite.com/products.php?lc=pt
Same links with prettyURLs -
- Code: Select all
http://yoursite.com/en/products/
http://yoursite.com/pt/products/
Notice the 'en' and 'pt' in the links above.
And now since the different languages use distinct URLs, our problem would be resolved.
I am attaching a little addon here that does precisely that (and more).
This addon should also make the entire process of implementing the 'third' method ultra-simple as everything is neatly packaged in an addon (no 'switch.php', 'lang_switcher_menu.html' etc. required).
Some common requirements of a multi-lingual site are reflected in the following request by @JD -
Ideally, the site should detect the default language of the visitor's browser and switch accordingly to the language version (EN, DE, ES).
If, however, the visitor is not using one of the available site languages, the English version should be served as a standard.
Furthermore, I would like that the user is able to switch between those languages at any time on any site from the menu (little flag buttons to choose language version)
This addon should make it a breeze to get those done.
So let us get going and see how that happens.
Installation:
Before we install this addon, please make sure your setup fulfills the following prerequisites -
1. Get the current version of Couch from GitHub (https://github.com/CouchCMS/CouchCMS). For this addon to work, it'll need at least "Couch v2.0 Build 20170710" (as of this post date, this is the latest version at GitHub).
2. If you'd be testing this addon on an existing Couch site and the site uses prettyURLs, please make sure to turn prettyURLs off (from couch/config.php) before installing this addon.
Don't worry, we'll turn those back on later (as explained at the end of this post). To begin with, we need normal URLs.
With the prerequisites in place, we can begin the installation.
The procedure remains the same as all the other addons.
a. Extract the attached zip to get a folder named 'multi-lang'.
b. Place this folder within the 'couch/addons' folder of your installation.
c. Finally, activate this addon by adding the following entry in 'couch/addons/kfunctions.php' file (if this file is not present at the specified location, rename the 'kfunctions.example.php' file there to 'kfunctions.php') -
- Code: Select all
require_once( K_COUCH_DIR.'addons/multi-lang/multi-lang.php' );
Configuration:
Within the 'multi-lang' folder we placed above in the 'addons', you'll find a file named 'config.example.php'.
Rename it to 'config.php'. Open it in your favorite text editor and find the following setting in there -
- Code: Select all
// Accepted languages (code => display_name)
// get codes from https://docs.oracle.com/cd/E13214_01/wli/docs92/xref/xqisocodes.html
$cfg['langs'] = array(
'en'=>'English',
'fr'=>'French',
'pt'=>'Portuguese',
);
As you can see, as a sample, it already has three languages configured for use on your site.
You are supposed to make changes to this setting to specify the languages your site will work with. Please note that for every language specified in it, you'll also need to specify its 'language-code' ('lc' as it will referred to in the rest of this discussion). You can see the 'lc' for the three languages above. For other languages, if you are unsure of its code, you may get it from the link shown above.
For the purpose of this discussion, I'll assume that we accept the sample configuration and make our site use the three languages specified above.
OK, with that done, we are ready to use this addon.
Visit any page of your site and observe its URL in the browser's address bar - you'll see that Couch automatically adds 'lc=en' to the URL.
e.g.
- Code: Select all
http://localhost:8080/test.php?lc=en
http://localhost:8080/test.php?p=710&lc=en
That 'en' is used because it, being the first language specified in config, is treated as the default language and so when no language is specified in the URL it gets automatically selected. You can, of course, set your desired language as the default by placing it first in the config array we saw above.
Let us quickly create a language switcher to test out the other languages we specified.
Creating the language switcher menu:
If we were to place a <cms:dump_all /> tag in any template, we'll see that this addon makes available to us some variables that can aid us in implementing a multi-lingual site.
Assuming that the page being visited is
http://localhost:8080/test.php?p=710&lc=en
and three languages have been specified (en, fr and pt) in config, we'll see the following new variables -
- Code: Select all
k_lang: en
k_link_en: http://localhost:8080/test.php?p=710&lc=en
k_link_fr: http://localhost:8080/test.php?p=710&lc=fr
k_link_pt: http://localhost:8080/test.php?p=710&lc=pt
k_supported_langs: Array
A brief description of the variables -
k_lang
This will always contain the currently selected language (you'll remember that this value is one of the language-codes we specified in the config).
k_link_en
k_link_fr
k_link_pt
These links point to the current page in all the available languages - notice the 'en', 'fr', 'pt' (our language-codes) appended to 'k_link_'.
In this case, the three links are for the three languages we specified in config. If there were more languages or other languages, the links would reflect those languages.
As you can see, these can be used to create a language-switcher e.g.
- Code: Select all
<ul>
<li>
<a href="<cms:show k_link_en />">English</a>
</li>
<li>
<a href="<cms:show k_link_fr />">French</a>
</li>
<li>
<a href="<cms:show k_link_pt />">Portuguese</a>
</li>
</ul>
For quickly testing out the addon, you can use the menu above.
However, the next variable provides a more generic method of creating such language-switcher menus.
k_supported_langs
This is an 'array' (i.e. a compound variable) containing info about all the languages specified in config.
Try using it like this -
- Code: Select all
<cms:each k_supported_langs as='lang' key='lc'>
<cms:show lang />: <cms:show lc /> <br/>
</cms:each>
and it should output -
- Code: Select all
English: en
French: fr
Portuguese: pt
As you can see, the <cms:each> tag above iterates through all entries in 'k_supported_langs' and makes available each as two variables - 'lang' and 'lc'. These provide us with the names of all the specified languages and their codes.
We can then use those to create a generic language-switcher menu that will work across all configurations.
Here is a real-world example you may use as is or, as is more likely, use the technique in your own static design to convert an existing menu markup into a functional language switcher -
- Code: Select all
<ul id="languages">
<cms:each k_supported_langs as='lang' key='lc'>
<li lang="en" id="nav<cms:show lang />">
<a href="<cms:get "k_link_<cms:show lc/>" />">
<img src="<cms:show k_site_link />images/languages/flag-<cms:show lc />.jpg" alt="<cms:show lang />">
</a>
</li>
</cms:each>
</ul>
The code above outputs -
- Code: Select all
<ul id="languages">
<li lang="en" id="navEnglish">
<a href="http://localhost:8080/test.php?p=710&lc=en">
<img src="http://localhost:8080/images/languages/flag-en.jpg" alt="English">
</a>
</li>
<li lang="en" id="navFrench">
<a href="http://localhost:8080/test.php?p=710&lc=fr">
<img src="http://localhost:8080/images/languages/flag-fr.jpg" alt="French">
</a>
</li>
<li lang="en" id="navPortuguese">
<a href="http://localhost:8080/test.php?p=710&lc=pt">
<img src="http://localhost:8080/images/languages/flag-pt.jpg" alt="Portuguese">
</a>
</li>
</ul>
With proper styling, it looks like -
I'd like to draw your attention to two points above -
1. I renamed the images of flags I had, deliberately adding to each their respective language code (e.g. flag-en.jpg, flag-fr.jpg, flag-pt.jpg).
This way in the cms:each loop, I could use the <cms:show lc /> statement (outputting the language code) to show the flag belonging to the language being iterated.
2. More importantly, notice also how the flags are linked to their language versions of the *current* page.
So, if we place this menu in a snippet and make it display on all pages of our site, whatever page a visitor might be on, the flags will provide her with links to the *same* page in different languages.
Please notice how we are using <cms:get> coupled with <cms:show lc/> to output the values of 'k_link_en', 'k_link_fr' and 'k_link_pt' variables containing links of the current page in those languages -
- Code: Select all
<cms:get "k_link_<cms:show lc/>" />
As those familiar with the original "third method" (viewtopic.php?f=8&p=9010#p9010) will recall, the use of <cms:get> was pivotal in creating multi-lingual sites.
For those chancing upon this thread for the first time, please allow me a brief detour to explain the use of <cms:get> as this is used extensively further down (others may safely skip this section).
=================== begin detour ===============================
Please consider the following two statements -
- Code: Select all
<cms:show k_link_en />
<cms:get "k_link_en" />
Both will output exactly the same result (the English language link of the current page).
However, notice that the syntax of <cms:get> is different fron that of <cms:show> in that it requires "double-quotes" around the variable name - effectively this means that we are specifying a "string" as the variable.
This use of string opens up possibilities that are not available with <cms:show>. For example, consider this -
- Code: Select all
<cms:set my_lang='en' />
<cms:get "k_link_<cms:show my_lang />" />
In the code above, notice we are using another variable (my_lang) *inside* the <cms:get> input string. The value contained in 'my_lang' is 'en', so after substitution, the final string that <cms:get> will receive would be "k_link_en" i.e. the English language link.
Now if we were to change the value of 'my_lang' to 'fr', the <cms:get> will fetch fetch the "k_link_fr" link instead.
Point is that we can dynamically change the output of <cms:get> by changing the value of the variable(s) used in its input string.
This makes it possible for us to code 'language agnostic' statements using variables that will change with the current language of the site, for example consider this -
- Code: Select all
<cms:get "k_link_<cms:show k_lang />" />
The 'k_lang' variable, as you'll remember, will always contain the language-code of the currently selected language.
So, the statement above will automatically show the current page link in the language currently selected. If the current language is French, it will show the FR link. If the visitor switches over to English, it will automatically show the now current EN link.
It will work without any change everywhere without us needing to find out first as to which language is current and so which variable to show.
To illustrate the difference, following is the equivalent code using <cms:show> for our tri-lingual site -
- Code: Select all
<cms:if k_lang='en'>
<cms:show k_link_en />
<cms:else_if k_lang='fr' />
<cms:show k_link_fr />
<cms:else_if k_lang='pt' />
<cms:show k_link_pt />
</cms:if>
The code above, apart from being more verbose, is also non-portable as you'll have to change it if you happen to add more languages to the site or change the existing ones.
That ends our detour (hopefully having established the usefulness of <cms:get>).
=================== end detour ===============================
Creating the main site
Once the language switcher is in place, try clicking the different languages and see how the URL in the browser's address bar automatically shows the selected language. So now each language has its own distinct URL for every page on the site.
We are finally set to show the actual contents in the selected language.
This part remains almost exactly the same as that deployed in the original method.
Of all the editable regions created in any template, some are common to all languages (usually the assets e.g. images, thumbnails, files etc.).
For the actual textual contents, we'll create separate editable regions for each language supported by our site.
So suppose a template originally requires only two regions - one image and the other textarea.
For a normal site (i.e. not multi-lingual), we could define the regions as follows
- Code: Select all
<cms:template>
<cms:editable name="photo" type="image" />
<cms:editable name="content" type="textarea" />
</cms:template>
For our tri-lingual site, we'll define the regions as follows instead -
- Code: Select all
<cms:template>
<cms:editable name="photo" type="image" />
<cms:editable name="content_en" type="textarea" />
<cms:editable name="content_fr" type="textarea" />
<cms:editable name="content_pt" type="textarea" />
</cms:template>
As can be seen, we have defined separate regions for the three languages. The important part is that we have appended the respective language-codes to the names of the different regions. This will make it easy for us to show the correct region matching the currently selected language.
Let us do that.
First input some data into the three editable regions in the admin-panel for testing.
Now at the place in your template where you need to show the content, use the following -
- Code: Select all
<cms:get "content_<cms:show k_lang />" />
And that is it!
Switch between the languages and see how the content automatically changes to match the selected language.
By using this addon, that is all that you need to do for creating multi-lingual site -
1. Create editable regions with names containing the language-codes
2. Use <cms:get> to show the contents.
I think you'll agree, this addon makes the original method way easier to implement.
One last thing..
Ok, before we end the topic by turning on prettyURLs, there is one last point that I need to discuss.
As you must have realized, this new method banks upon the presence of the 'language-code' in *all* links present on any given page.
This is so that the visitor is always served pages only in the selected language. To illustrate the point, suppose a visitor selects 'pt' as her language. Now all the links on any page she visits should have 'pt' attached else she could land up on a different language thus breaking her context.
This addon tries to automatically add the language-code to most links on pages. I'd say, it succeeds in doing this for 95% of the links (notably all 'k_page_link' and links generated by <cms:link> tag). However, there are a few links which escape this treatment (primarily because making this addon manipulate those links would mean making sweeping changes to Couch's core).
I cannot provide an exhaustive list of variables containing such links but only a modest amount of testing applied to your fully implemented site should easily reveal those. One thing is certain about them though - all of them will definitely have the term 'link' in their names. So you can keep an eye on such variables while coding also.
For such links, this addon provides a tag named <cms:show_with_lc> that does the conversion for you.
The use is pretty easy. Take a look at the following -
- Code: Select all
<cms:if k_paginated_bottom >
<cms:if k_paginate_link_prev >
<a href="<cms:show k_paginate_link_prev />">prev</a>
</cms:if>
<cms:if k_paginate_link_next >
<a href="<cms:show k_paginate_link_next />">next</a>
</cms:if>
</cms:if>
The code above is some regular code involving pagination. Unfortunately, the 'k_paginate_link_prev' and 'k_paginate_link_next' are language-code unaware. To rectify that, we simply need to modify the '<cms:show >' part to '<cms:show_with_lc>' (i.e. 'show with language-code'). Our modified code becomes -
- Code: Select all
<cms:if k_paginated_bottom >
<cms:if k_paginate_link_prev >
<a href="<cms:show_with_lc k_paginate_link_prev />">prev</a>
</cms:if>
<cms:if k_paginate_link_next >
<a href="<cms:show_with_lc k_paginate_link_next />">next</a>
</cms:if>
</cms:if>
As you can see, it required a simple substitution at only two places.
[
For more complex pagination needs, do the same with 'k_crumb_link' variable. Please see -
viewtopic.php?f=4&t=10796
viewtopic.php?f=8&t=10168
]
Wrapping up
Once the site is complete and you are satisfied with the way things are working, the final thing to do should be turning on the prettyURLs (that is, if you do want to use those on the site).
Follow the standard way of doing this (http://docs.couchcms.com/concepts/pretty-urls.html) -
first edit couch/config.php to turn prettyURLs on. Then generate rewrite rules for putting into .htaccess file (the bottom of the sidebar in admin-panel now has a link for doing this). Copy and paste those rules into a .htaccess file and place that file in your site's root.
If your site was already using prettyURLs before activating this addon then you'll likely already have a .htaccess file you generated previously.
You'll still need to regenerate the rules and place them into the .htaccess file because this addon will add new rules of its own that have to be placed in the .htaccess file.
The last line is important - using prettyURLs with this multi-lingual addon expects a new set of rules in .htaccess file. So, in the future, if you happen to add a new language or modify the language-code of any existing language, you'll need to regenerate the rules and then update the .htaccess file with them.
With that done, access your site and take a look at the URLs it uses now. You should see something like -
- Code: Select all
http://yoursite.com/en/products/
http://yoursite.com/en/products/gadgets.html
http://yoursite.com/pt/products/
http://yoursite.com/pt/products/gadgets.html
Notice how this addon has added the language-codes *before* the template names so as to make it appear as if the templates were in subfolders named 'en/' and 'pt/' etc. So, in a way, the URLs now match those that we get using the 'second method' of creating multi-lingual sites.
That ends this post. Hope our members find this addon useful.
Please feel free to ask any questions you might have.