[+txt_page_documentation_title+]

[+txt_page_documentation_about_title+]

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+]

Setup

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.

Starting from scratch or from a mono-lingual site

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 by Step YAMS Setup
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 modes

Server Name mode and Root Name mode can be used simultaneously or independently. The general format of the URL when using these modes is:
http://(server_name)/(root_name)/(path/)(filename)
where there is only a path if friendly alias paths have been configured.

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 mode

Query 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:
http://server_name/(path/)filename?yams_lang=id

By default this query param is called yams_lang. However, it is configurable on the Other Options tab. Change it to lang for compatibility with EasyLingual.

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: description_id

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 q query parameter. To help with this, YAMS provides you with text that you can copy and paste. See the Server Config tab. As a bonus, this text will tell YAMS the current language via a query parameter, which saves it from having to figure it out from the URL later.

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
(yams_doc:docId) or (yams_docr:docId)
and in templates is
(yams_doc:[+docId+]) or (yams_docr:[+docId+]).

This will provide a full absolute URL to the given document. The yams_docr version will additionally resolve weblinks if that is required. These two placeholders can be configured not to output the filename of the document for the site start. See the 'Other Params' tab. This approach will work for all YAMS setups and is not dependent on a particular base meta tag setting.

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:

  • [~docId~] becomes (yams_root/:docId)[~docId~]
  • [~[+docId+]~] becomes (yams_root/:[+docId+])[~[+docId+]~]
  • [(site_url)][~docId~] becomes [(site_url)](yams_root/:docId)[~docId~]
  • [(base_url)][~docId~] becomes [(base_url)](yams_root/:docId)[~docId~]
  • etc.

You could of course choose to include the root name in the base meta tag (by setting the href attribute to (yams_site) for example.) However, please be aware that in that case you will have to provide a complete URL to all file based resources. For example: [(site_url)]assets/images/...

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: lang="(yams_tag)" and/or xml:lang="(yams_tag)" and dir="(yams_dir)"

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 (yams_mname) placeholder to access the correct manager language for use in snippet calls. For example, with ditto and eForm, &language=`(yams_mname)` can be used.

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:
require( $modx->config['base_path'] . 'assets/modules/yams/yams.mm_rules.inc.php' );

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
[[yams? &get=`list`]]
or
[[yams? &get=`selectform`]]
to include a list based or form based language selection tool into your template. These commands can now be modified using custom templates. See the snippet documentation for more details.

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.

Migrating from an EasyLingual site

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.

  • First back up. (See step 1 above.)
  • On the Other Params tab select the EasyLingual Compatibility Mode setting to Yes and change the Confirm Language Param setting to lang.
  • You will have to use Query Param mode. (See step 2 above for details.)
  • Configure your languages using the Language Settings tab. (See step 3 above.) Leave all server name fields blank. (The default site url will be displayed in brackets.) Leave the root names fields blank.

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.

YAMS Placeholders

YAMS Placeholders

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>

YAMS placeholders
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

EasyLingual Compatibility Placeholders

GetEasyLingualCompatibility() ) { ?>

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.

  • By far the biggest difference between YAMS and EasyLingual is the fact that YAMS has the concept of monolingual and multilingual templates (and hence documents). Multilingual documents contain content in multiple languages, and for such documents YAMS will automatically replace certain document variables, such as [*pagetitle*], by their correct language multi-language version, equivalent to [*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.
    Since EasyLingual doesn't have the concept of a mono- and multi-lingual documents, the EasyLingual placeholders are set up to react to the language specified by the 'Confirm Language' query parameter on monolingual pages rather than using the default language. (See the 'Other Params' tab.) The effect of this is that an EasyLingual site should continue to function as normal using only monolingual templates. However, there is always the option to switch off EasyLingual Compatibility Mode or to switch to using multilingual templates at any time.
  • The way that YAMS and EasyLingual parse placeholders is different. Because of the way YAMS is designed placeholders can appear almost anywhere, including in chunks, and it is possible to use them with both cacheable and uncachable documents and snippets. In fact, with YAMS, using cacheable documents and snippets everywhere possible is positively encouraged, and YAMS is designed to work most efficiently in this mode.
  • There are restrictions on the use of {{[%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.
  • With YAMS, the language group identifier, which is used to name template variable variants, can be different to the language tag (en-gb etc.) Multiple language tags can be applied to a language and they can be in the form of a language code only or a language code followed by a dash and a locale code. The [%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 can run in several different modes, allowing you to identify the current language in different ways via the URL. The server name can be different, or the root folder name can be different for example. To be completely compatible with EasyLingual you have to run YAMS in Query Param mode. In this mode the current language is specified by a query parameter. The name of that query parameter can be configured on the 'Other Params' tab. By default it is yams_lang, but for compatibility with EasyLingual you should change it to lang.
EasyLingual Compatibility placeholders
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.

Snippet

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.

YAMS Snippet
Parameter Values Description
&get
  • chunk
  • csnippet
  • usnippet
  • tv
  • placeholder
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, &currenttpl and &aftertpl parameters. If a &currenttpl 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, &currenttpl 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, &currenttpl 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, resource_name. On multilingual pages this will be replaced by a construct that includes one language variant for each active language group. The language variants are assumed to have the name resource_name_id, where id is the language group id. These language variants are subject to normal MODx caching. When a request is made for the document in a given language, all incorrect language variants are stripped out, allowing the user to see only the correct language content.

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 &get=`text`, the resource name can be replaced by text to be output instead, but any pipes should be escaped with a backslash.

&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 &currenttpl param.
&currenttpl 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.

Constructs

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.

YAMS Constructs
Construct Name Description
(yams-in:yamsId:langId)...content...(/yams-in:yamsId) YAMS In Language Block

Forces the content of the yams-in block to be displayed as if the current language is that specified by the language group identifier langId.

Here yamsId is a positive integer identifier that should be unique to this block. This allows blocks to be nested. langId is a language group id.

(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 pagetitle, longtitle, description, introtext, menutitle and content document variables are automatically expanded into this form for the currently defined active languages. For any other content (chunks, tvs, etc.) that need to be expanded into multi-language form a YAMS snippet call can be used to generate the relevant construct.

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 yamsId is a positive integer identifier that should be unique to this block. This allows blocks to be nested. langId is a language group id.

(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 yams-repeat block will repeat any content once for each active language and is similar to specifying one yams-in block for each active language. The current sub-block is optional, and allows you to specify an alternative template to be used with the current language content.

Here yamsId is a positive integer identifier that should be unique to this block.

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

How To? (FAQ)

Make Ditto work with YAMS?

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

Make Wayfinder work with YAMS?

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.

Make eForm work with YAMS?

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.

Make other snippets work with YAMS?

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.

Use a different document template for each language?

  • Place the document template for each language within a separate chunk. Give the chunks the names mytemplate_id1, mytemplate_id2, etc. where id1, id2, ... are the language group ids for your active languages.
  • In place of your standard document template, use the following snippet call:
    [[YAMS? &get=`chunk` &from=`mytemplate`]]

Have a language selection site start/landing page?

  • Create a new template to use for your landing page.
  • From within the YAMS Module, select that template as not multilingual or multilingual as you see fit. (Select multilingual if you want to let the YAMS decide to guess the language to display on the landing page based on the user's browser settings. See the Other Params tab.)
  • Modify your MODx site start document to use the landing page template
  • Create a chunk containing the following template called LandingPageRepeat, say:
    <li><a href="(yams_docr:docId)" title="[[YAMS? &get=`content` &from=`pagetitle` &docid=`docId`]]" >(yams_name)</a></li>
    Replace docId by the identifier of the document that you want the user to be redirected to from you landing page.
  • Somewhere in the template, use the following code to include a hyperlinked list of all available languages:
    <ul>[[YAMS? &get=`repeat` &repeattpl=`LandingPageRepeat`]]</ul>

Include all language variants in your site map?

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:

  • You should have a ditto call that loops over all documents and creates your sitemap url elements. Place your ditto call into a chunk called SitemapRepeat.
  • Make sure that your site map document is monolingual.
  • Within your sitemap document, place the following snippet call:
    [[YAMS? &get=`repeat` &repeattpl=`SitemapRepeat`]]
    This will repeat your ditto call one time for each language variant.

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.

More to add...