YAMS: [+txt_page_documentation_about_short_description+]
[+txt_page_documentation_about_author_title+]: [+yams_author+]
[+txt_page_documentation_about_donate_title+]: [+yams_author+]
[+txt_page_documentation_about_version_title+]: [+txt_page_documentation_about_version_text+]
[+txt_page_documentation_about_copyright_title+]: [+yams_copyright+]
[+txt_page_documentation_about_licence_title+]: [+yams_licence+]
[+txt_page_documentation_about_forums_title+]:
[+txt_page_documentation_about_new_title+]:
[+txt_page_documentation_about_new_text+][+txt_page_documentation_about_description_title+]:
[+txt_page_documentation_about_description_text+]Credits: [+txt_page_documentation_about_credits_text+]
These instructions aim to tell you how to set up a new site or convert an existing site to be multilingual in a way that will cause you the least disruption. In theory it's possible to convert your site to a multilingual one without having to take it off line for more than a second while you reload your server config. If everything goes smoothly, then at no point should your website be broken during the setup process.
There are two sets of instructions. The first is for those people who are starting from scratch and want to develop a multilingual site, or those or have a monolingual site and would like to add additional languages. The second is for those people who are already using the EasyLingual solution and would like to convert to using YAMS so as to benefit from caching and all the other benefits that YAMS brings.
It will be assumed that you have already installed the YAMS module, plugin and snippet. The DocFinder module can come in really useful for updating your URLs, but it is not obligatory. I highly recommend installing the ManagerManager plugin, since YAMS can use it to organise the multiple language fields into separate tabs and to hide redundant document variable fields on the document view.
YAMS has been designed to work with friendly URLs. It should work with friendly alias paths on, but this has not yet been thoroughly tested.
The default YAMS install does nothing. You have to set it up to switch on the multilingual functionality that you need.
Step | Action | Description |
---|---|---|
Ensure you're backed up |
This is an alpha version after all. |
|
Decide on URL format |
Before you start configuring you need to decide how you will identify the different languages groups in the URL. There are three modes that can be used: Server Name mode, Root Name mode and Query Param mode. Whatever combination of modes you choose, the full URL must be unique for each language and you will need to configure your server settings appropriately. Server Name and Root Name modesServer Name mode and Root Name mode can be used simultaneously or independently.
The general format of the URL when using these modes is: When server name mode is OFF the server name is determined in the normal way MODx determines it and so is consistent with MODx [(site_url)]. Server name mode is switched ON by specifying a different server name for each language group and a server name for monolingual/ordinary pages on the Language Settings tab. To use server name mode, you will have to configure the various server names as aliases or virtual hosts on your server. To enable root name mode, you just need to specify at least one root name on the Language Settings tab. If server name mode is OFF then you will need to specify one per language group. In either of these modes it is possible to change the language of a page by sending a request back to current page with the id of the new language group specified with a GET or POST variable. By default this variable is called yams_new_lang, but it can be configured on the Other Params tab. There is also a placeholder that can be used to access this name and snippet calls that will generate a list or drop down box to enable changing the language. Query Param modeQuery Param mode is provided primarily for compatibility
with EasyLingual and cannot be used in conjunction with the other modes.
In this mode there is no root name and the server name is identical for all
language groups. So, to distinguish one language from another a query parameter
is appended to all URLs:
By default this query param is called yams_lang.
However, it is configurable on the Other Options tab.
Change it to |
|
Configure Language Settings |
The second step is to configure the language settings for each language group that will be used on your multilingual pages. This is done on the language settings tab. Each language group has an id. This is used, for example, in the multilingual versions of the template variables for that language. Eg: A language group can be set up to represent a group of languages (en), a specific localised language (en-gb) or a selection of localised languages (en-gb,en-us,...) by specifying a comma separated list of language tags. In addition to this and the server name and root name for each language group, you can specify the language direction and the text associated with each language. You can also associate a MODx language name with the language group. You will now need to set up one language group as the default language group. This language will be assumed for non-multilingual pages. |
|
Update Friendly URLs config |
If you are using server name or root name mode then
you will need update your .htaccess file to strip the
root directory name from the beginning of the request
URI (if necessary) and send MODx the correct You will have to update your server config every time you activate or deactivate a language group, change its server or root name, or rename the query parameter. Note that your website should continue to function normally. |
|
Update URLs |
The next step is to update all URLs to internal documents and weblinks so that they will function as multilingual URLs on multilingual pages and normal URLs otherwise. Links to real files like images are not affected by the YAMS module and do not need to be converted. To convert an URL you use the YAMS placeholders. The recommended way of specifying URLs in documents is This will provide a full absolute URL to the given document. The However, if you are ONLY using root name mode and are not planning on using server name mode in the future then you may find it simpler to prefix the page alias by the root name instead. For example:
You could of course choose to include the root name in the base meta tag (by setting the href attribute to Remember that by default all pages are monolingual, so none of these replacements should break or alter the way your website functions. |
|
Update Language Tags and Direction |
The next step is to update your language and language direction attributes, again using YAMS placeholders: |
|
Update Snippets |
The next step is to update any snippets which output URLs or directly contain multilingual text that is not embedded in multilingual placeholders. Guidance on how to do this for Wayfinder, Ditto, eForm and other snippets is on the 'How To?' tab. Note that you can use the |
|
Redirection Strategy |
You are now at a stage where you can start to specify certain templates as multilingual templates. All documents associated with those templates will have multiple language versions - but they will all be managed via the same document within the manager. Note that when you specify a template as multilingual, the URLs of the associated documents will change. YAMS will automatically redirect from the old URLs to a language variant. Several redirection modes are available. Initially you should choose the default language mode. Only once you have written content for the other languages should you switch. These settings are configured on the Other Params tab. I'd recommend setting the HTTP status code for the redirect to temporary until you are confident you want to go live. |
|
ManagerManager Interface |
If you haven't installed ManagerManager yet and are planning to, then now is the time to do it. It is highly recommended. Once you have done it, insert the following line into your mm_Rules configuration file to enable YAMS to integrate with it: You will subsequently be able to specify how the fields in your multilingual documents will be organised via the settings on the Other Params tab. When you convert a document to be a multilingual document the existing document variables, including the pagetitle, retain their existing values. However, all but the pagetitle become redundant. The YAMS ManagerManager rules will hide the redundant document variables. With YAMS, the document pagetitle takes on the role of a text identifier for the document and all its language variants within the MODx back-end. This identifier is visible in the MODx document tree, but not on any web output. For convenience, YAMS provides an option to automatically update this document pagetitle with the contents of the default language multilingual pagetitle template variable on document save. This can be enabled via the option on the 'Other Params' tab. |
|
Multilingual Templates |
You are finally in a position to be able to specify certain templates as multilingual. You do this from the Multilingual Templates tab. I recommend leaving the automatic template variable management setting to yes. Note that this is a beta version though, so make sure you are all backed up before hand. All you have to do is select yes for those templates that you want to be multilingual. If you want to experiment first, create a new template, associate it with a new document, populate it with some default content and play with that. Assuming you selected yes for automatic template variable management, making it multilingual will create multiple versions of each template variable for each language, associate it with the template and copy over the default content for your document into the newly created default language template variables. |
|
Translate |
You can now view multiple language versions of your documents by browsing to the appropriate URL. However, initially all but the default language version has content written for it. Now is the time to go to each document and translate the content. Note that your site will continue to look normal and there wont be any links pointing to your new language versions until you jump to the next step. |
|
Publicise |
Once your content is translated, you are in a position to publicise it. You can use the snippet calls |
|
All Done |
Your site is now up and running as a multilingual site. You can change the redirection mode if you like and can change the http status once you are happy that you are going to keep your site as a multilingual site. Make sure your search engine site map contains a list of all documents, and not just those of a single language. See the How To tab for more details about how to achieve this. |
Warning! I have never actually tried to convert an EasyLingual site before. I have just read about how it is supposed to work from the EasyLingual forum thread. Looking for feedback from volounteers willing to try it out.
lang
.Your site should now be working as it was under EasyLingual. If it isn't then take a look at the EasyLingual tab for info about the EasyLingual compatibility placeholders. If that still doesn't solve your problem them please post a message to the YAMS forum thread. Some additional adjustments may be needed or there may be a bug.
Two forms of each placeholder are available. In the first form, (yams_???)
,
the placeholders provide information about the current document.
In the second form, (yams_???:docId)
, they provide information about the document
with the given document identifier, docId
.
It should be possible to use snippet calls and chunks to obtain
the document identifier for the document identifier.
(yams_doc:[+id+])
can be used within templates.
It should be possible to use YAMS placeholders almost anywhere, including in chunks, in the names and output of template variables, and in the names, output and parameters of snippet calls.
When the output of a YAMS placeholder is language dependent it needs to know what the current language is. The current language is dependent upon the context. The (yams-in)
or (yams-repeat)
blocks allow the inclusion of alternate language content on a page. (See the Constructs tab). If a placeholder falls within either of these blocks, then the current language is that specified by those blocks. Otherwise the current language is taken to be the language in which the current page is being displayed. There may be occasions when you would like to override this behaviour, and force the placeholder to treat the current document language as the current language. This can be achieved by appending a +
symbol to the end of the name of the placeholder. For example, the following will generate a (yams-repeat) block that will display a list of the names of the available languages, all written in the current document language:
<ul>[[YAMS? &get=`repeat` &repeattpl=`@CODE:<li>(yams_name_in_(yams_id+))</li>`]]</ul>
Placeholder | Monolingual Document | Multilingual Document |
---|---|---|
(yams_id) (yams_id:docId) |
The default language id | The current language id |
(yams_tag) (yams_tag:docId) |
The primary language tag for the default language | The primary language tag for the current language |
(yams_root) (yams_root:docId) |
Nothing | If specified and non-empty, the server root name for the current language, else nothing |
(yams_/root) (yams_/root:docId) |
Nothing | If specified and non-empty, the server root name for the current language preceded by a /, else nothing |
(yams_root/) (yams_root/:docId) |
Nothing | If specified and non-empty, the server root name for the current language followed by a /, else nothing |
(yams_site) (yams_site:docId) |
If server name mode is ON, an URL created using the specified monolingual server name. If server name mode is OFF, the same output as [(site_url)]. | The full multilingual site url including server name and server root as required for the current page. |
(yams_server) (yams_server:docId) |
Same as for yams_site . |
Same as for yams_site , but with no root name. |
(yams_doc) (yams_doc:docId) |
A complete URL for the document or weblink. There is an option on the 'Other Params' tab that will suppress the filename for the site start document. | A complete URL for the current language version of the document or weblink. There is an option on the 'Other Params' tab that will suppress the filename for the site start document. |
(yams_docr) (yams_docr:docId) |
Same as for yams_doc , but weblinks are resolved. |
Same as for yams_doc , but weblinks are resolved. |
(yams_dir) (yams_dir:docId) |
The language direction ('ltr' or 'rtl') for the default language | The language direction ('ltr' or 'rtl') for the current language |
(yams_align) (yams_align:docId) |
The text alignment ('left' or 'right') for the default language | The text alignment ('left' or 'right') for the current language |
(yams_mname) (yams_mname:docId) |
The MODx language name for the default language | The MODx language name for the current language |
(yams_confirm) (yams_confirm:docId) |
The name of the Confirm Language param. (See the Other Params tab.) | The name of the Confirm Language param. (See the Other Params tab.) |
(yams_change) (yams_change:docId) |
The name of the Change Language param. (See the Other Params tab.) | The name of the Change Language param. (See the Other Params tab.) |
(yams_name) (yams_name:docId) |
The name of the default language in the default language | The name of the current language in the current language |
(yams_name_in_langId) (yams_name_in_langId:docId) |
The name of the default language, written in the language specified by the langId language group id. |
The name of the current language, written in the language specified by the langId language group id. |
(yams_choose) (yams_choose:docId) |
The Select Language Text, written in the default language. (See the Language Settings tab.) | The Select Language Text, written in the current language. (See the Language Settings tab.) |
EasyLingual Compatibility Mode is currently ON. The EasyLingual compatibility placeholders are available.
EasyLingual Compatibility Mode is currently OFF. To use these placeholders, please activate EasyLingual Compatibility Mode from the 'Other Params' tab.
The following placeholders are to help ease the transition from a site already using EasyLingual to one using YAMS. A site written using the EasyLingual plugin may not work directly and immediately with YAMS since there is not a precise correspondence between YAMS and EasyLingual placeholders and the behind-the-scenes parsing that YAMS does follows different rules to those of EasyLingual. Having said that, YAMS should be more flexible and forgiving overall. A list of the most important differences is listed below.
[*pagetitle_[%LANG%]*]
. Monolingual documents are intended to be just that, and YAMS placeholders are configured to treat such pages as if they are in the default language.{{[%LANG%]_name}}
style syntax. This will work if it appears directly in the document template. However, if this is placed in a document or template variable then it will not work. The reason for this is that MODx tries to evaluate chunks immediately after having evaluated document and template variables. Since there is no event that YAMS can plug into between the two, it is impossible for it to parse the [%LANG%]
placeholder beforehand. (This restriction almost certainly applies to EasyLingual too.) It is worth mentioning that in YAMS there are other ways of achieving the same thing. For example, if the naming convention of the chunk is reversed (name_[%LANG%]
), then you can do: [[YAMS? &get=`chunk` &from=`name`]]
. This should work anywhere.[%lang%]
and [%LANG%]
compatibility placeholders have been set up to output the primary language tag. To be compatible with EasyLingual, you should restrict yourself to specifying a two digit language code for the primary language tag, and the language group id should be given the same value.yams_lang
, but for compatibility with EasyLingual you should change it to lang
.Placeholder | Monolingual Document | Multilingual Document |
---|---|---|
[%lang%] |
The primary language tag for the current language, unless it is the default language, in which case nothing is output. | Same as for monolingual documents. |
[%LANG%] |
The primary language tag for the current language | Same as for monolingual documents. |
[%language%] |
The MODx language name for the current language, unless it is the default language, in which case nothing is output. | Same as for monolingual documents. |
[%LANGUAGE%] |
The MODx language name for the current language. | Same as for monolingual documents. |
[%dir%] |
The language direction ('ltr' or 'rtl') for the current language | Same as for monolingual documents. |
[%align%] |
The text alignment ('left' or 'right') for the current language | Same as for monolingual documents. |
The YAMS snippet call is used for obtaining and outputting multilingual content stored in document variables, template variables, chunks, snippets or whatever in the correct language. It is also used for repeating content in multiple languages based on templates. By selecting the list, select or selectform options the same approach is used together with a default (but overridable) set of templates to create a hyperlinked list of language versions or a drop down select box of languages to enable switching the current language.
The YAMS snippet is in fact a macro for creating special constructs described on the next tab. These constructs include all possible language versions of the content. These blocks are reorganised and optimised as much as possible before a document is cached. This helps to ensure that as little parsing as possible is required to select the correct language content once it has been retrieved from the cache. Note that language selection occurs after a document is retrieved from the cache, so it is not possible to end up caching the wrong language content. It is important that the YAMS snippet is run as a cacheable at all times, since this will allow pre-cache optimisation to be undertaken.
See the How To? tab for examples of its use.
Parameter | Values | Description |
---|---|---|
&get |
|
These parameters choose from multiple language versions of a {{chunk}} , [[cacheable snippet]] , [!uncacheable snippet!] , [*template variable*] or [+placeholder+] and display the correct one depending on the current language. Use the &from parameter to specify the names of the resources to choose from. |
text |
In this case, the &from parameter will accept plain text in multiple languages rather than the name of a resource. |
|
content |
This parameter is used to extract multilingual content from the document or template variables of specific documents. In this case, the &from parameter specifies the the names of the document or template variables from which the content will be extracted and &docid specifies the document identifier. This is primarily for use in the templates of snippets which don't understand multilingual variables. See the YAMS How To for more information. |
|
repeat |
Repeats multiple language versions of content on a page. This option works using the templates specified by the &beforetpl , &repeattpl , ¤ttpl and &aftertpl parameters. If a ¤ttpl template is specified, then it is used in place of &repeattpl for the current document language. Otherwise, the &repeattpl template is repeated for all languages. |
|
list |
This functions in the same way as &get=`repeat` except that by default it uses the templates in assets/modules/yams/tpl/yams/list/ to create a list of hyperlinks to the different language versions of the page. These default templates can be overridden using the &beforetpl , &repeattpl , ¤ttpl and &aftertpl parameters. |
|
selectform |
This functions in the same way as &get=`repeat` except that by default it uses the templates in assets/modules/yams/tpl/yams/selectform/ to create a select box and form allowing users to change language. These default templates can be overridden using the &beforetpl , &repeattpl , ¤ttpl and &aftertpl parameters. |
|
select |
This functions in the same way as &get=`selectform` except that it only outputs the select box, not the form. |
|
&from |
resource_name |
This parameter enables you to specify the names of the snippets etc. in which the information lies. It has two forms: In the first, simpler form, you specify a name of a resource, say, |
id1:resource_name1|id2:resource_name1|... |
In the second, more complex form, you specify which languages and what name to use for the resource in each language. Here id1, id2, ..., are the language group ids, and resource_name1, ... are the full corresponding resource names. When using |
|
&docid |
A document identifier | The document identifier of the document from which to obtain the data. This is for use with the &get=`content` parameter. |
&beforetpl |
a chunk name@CODE:template code @FILE:path to template file
|
Specifies a template to be placed before a repeat block. |
&repeattpl |
a chunk name@CODE:template code @FILE:path to template file<>
|
Specifies a template to be repeated once for each active language. Can be overridden by the ¤ttpl param. |
¤ttpl |
a chunk name@CODE:template code @FILE:path to template file
|
Specifies a template to be used if it is in the same language as the current document. Overrides by the &repeattpl . |
&aftertpl |
a chunk name@CODE:template code @FILE:path to template file
|
Specifies a template to be placed after a repeat block. |
These constructs are used internally by YAMS, which also manages the yamsId
parameter to avoid clashes. They are provided here for reference only. Under normal circumstances these constructs do not need to be used. Instead a YAMS snippet call should be used, which will automatically generate the correct constructs.
Construct | Name | Description |
---|---|---|
(yams-in:yamsId:langId)...content...(/yams-in:yamsId)
|
YAMS In Language Block |
Forces the content of the Here |
(yams-select:yamsId)(lang:yamsId:langId1)...content1...(lang:yamsId:langId2)...content2...(/yams-select:yamsId)
|
YAMS Select Language Block |
This includes multiple language versions of content in the page. Only the current language version is displayed (except if it is within a yams-repeat block -- see below.) The When a Yams Select block is being parsed to select the correct language content the current language is taken to be context dependent. Within Yams In blocks (and branches of Yams Repeat blocks which ultimately resolve to Yams In blocks) the current language switches to the specified language. Here |
(yams-select+:yamsId)(lang:yamsId:langId1)...content1...(lang:yamsId:langId2)...content2...(/yams-select+:yamsId)
|
YAMS Select Plus Language Block |
This is the same as the Yams Select block, except that the current language is not context sensitive. So, the current language will always be the language in which the page is being viewed. |
(yams-repeat:yamsId)...content...(current:yamsId)...current language content...(/yams-repeat:yamsId)
|
YAMS Repeat Language Block 1 |
The Here |
(yams-repeat:yamsId:langId1,langId2,...)...content...(/yams-repeat:yamsId)
|
YAMS Repeat Language Block 2 |
This variation on the YAMS Multi-Language Block will only repeat for the specified language groups. This functionality is not currently accessible via a YAMS Snippet call. |
A YAMS extender has been written for ditto which will allow you to use your existing ditto templates, but which will pull in the correct language content depending on how the output is being viewed. To install the ditto extender, simply add the
&extenders=`@FILE assets/modules/yams/yams.extender.inc.php`
parameter to your ditto calls.
In addition, it is possible to use
&language=`(yams_mname)`
to make ditto operate and provide error messages in the correct language (as specified by the MODx Language Name field for each language on the Language Settings tab.)
Multilingual versions of the default Wayfinder templates are available, which will display the output in the correct language for the current page. To use the multilingual templates, add the following parameters to your snippet call, where the mode
folder is replaced by doc
or docr
:
&rowTpl=`@FILE:assets/modules/yams/tpl/wayfinder/mode/row.tpl` &parentRowHereTpl=`@FILE:assets/modules/yams/tpl/wayfinder/mode/parentrowhere.tpl` &parentRowTpl=`@FILE:assets/modules/yams/tpl/wayfinder/mode/parentrow.tpl` &hereTpl=`@FILE:assets/modules/yams/tpl/wayfinder/mode/here.tpl` &innerRowTpl=`@FILE:assets/modules/yams/tpl/wayfinder/mode/innerrow.tpl` &innerHereTpl=`@FILE:assets/modules/yams/tpl/wayfinder/mode/innerhere.tpl` &activeParentRowTpl=`@FILE:assets/modules/yams/tpl/wayfinder/mode/activeparentrow.tpl` &categoryFoldersTpl=`@FILE:assets/modules/yams/tpl/wayfinder/mode/categoryfolders.tpl` &startItemTpl=`@FILE:assets/modules/yams/tpl/wayfinder/mode/startitem.tpl`
The doc
creates full absolute URLs to the documents or weblinks. This should be used if your Wayfinder &useWeblinkUrl
setting is FALSE.
The docr
is the same as doc
, but additionally resolves weblinks. This should be used if your Wayfinder &useWeblinkUrl
setting is TRUE.
The simplest solution for eForm (and any template that contains free text) is to use the text mode of the YAMS snippet to incorporate your multi-language text variants directly. For example:
[[YAMS? &get=`text` &from=`en:Your name|fr:Votre nom|...`]]
Once again, it is possible to use the &language=`(yams_mname)`
parameter with eForm to ensure that it displays error messages in the correct language.
If the snippet uses templates, then you will have to convert the template to display the correct language content. This should be as simple as replacing the placeholders for the standard document variables: [+pagetitle+]
, [+longtitle+]
, [+description+]
, [+introtext+]
, [+menutitle+]
and [+content+]
by a YAMS snippet call:
[[YAMS? &get=`content` &from=`document_variable_name` &docid=`[+id+]`]]
and including language variants for free text using the text mode YAMS snippet call as described above.
See the Snippet tab for more details.
mytemplate_id1
, mytemplate_id2
, etc. where id1
, id2
, ... are the language group ids for your active languages.[[YAMS? &get=`chunk` &from=`mytemplate`]]
<li><a href="(yams_docr:docId)" title="[[YAMS? &get=`content` &from=`pagetitle` &docid=`docId`]]" >(yams_name)</a></li>
docId
by the identifier of the document that you want the user to be redirected to from you landing page.
<ul>[[YAMS? &get=`repeat` &repeattpl=`LandingPageRepeat`]]</ul>
Rather than having one site map per language, you may want to include all language variants of all pages in a single site map. If your site has multilingual pages only, then achieving this is quite simple:
url
elements. Place your ditto call into a chunk
called SitemapRepeat.[[YAMS? &get=`repeat` &repeattpl=`SitemapRepeat`]]
If you will have mono- and multilingual documents in your
sitemap then you will need to be more sophisticated. You will need two
ditto calls. One which loops over all documents that are associated
with multilingual templates and one which loops over all documents
associated with monolingual templates. You can achieve this
using Ditto's &filter
parameter. The multilingual
Ditto call will need to be placed in a chunk and repeated using
the YAMS snippet call described above.