### MMS help

In a multilingual environment, MMS unifies handling of all translations at once for any block, node, or structural content without using separate containers, and with only the Drupal core _Locale_ module activated.

<section>

#### How it works

Briefly said, MMS works upon all `< input type="text" >` and `< textarea >` elements, giving them the ability to contain their own whole set of translations.

In administration context, each of these areas is replaced by a multilingual widget where the user can instantly look at all translations of the content, and edit them at its option. Another, dedicated widget is also available for areas managed with CKEditor.

The benefits of using this method are mainly:

*   when entering new content or updating an existing one, authors keep a total visibility upon all the translations at the same time
*   a direct consequence is to reduce the risk of omitting to update the translations when an original content has been modified
*   when a content includes a lot of lang-insensitive data (like images, links, or simply verbous HTML with a number of attributes), these parts don't have to be duplicated: only the textual parts must be entered as "multi" and rewritten in the different languages
*   since it emulates the SPIP `< multi >` syntax, this method is nicely suitable to allow the direct migration of contents from this CMS, without the need of a painful data restructuration
*   moreover, in the latter case, authors can maintain their previous work habits unchanged

The advantages of using MMS are essentially:

*   it works for any content without needing other dedicated translation modules
*   it offers a unique interface for the user to watch and manage all translations at the same time for each content
*   it uses less database space (less tables, less duplicated content)

At the opposite it implies some limitations:

*   it does not allow to manage separate nodes for different languages
*   currently it reduces the available space for "small" contents (such as titles), because their allowed size is shared by all translations  
    _NOTE: this limitation will be lifted in a future version_

</section>

<section>

#### Installation/Configuration

_MMS_ works without the need of any other translation module, assumed you have activated the _Locale_ Drupal core module, and configured the desired languages. Nevertheless you can simultaneously use alternative translation methods, like _Multilingual Content_, _Menu translation_ etc.

The module is installed with a default configuration that is suitable for most use cases, and that you can fine tune to your wishes (see [Advanced configuration](#advanced) below). To immediatlely use the MMS capabilities you simply:

*   in "Administer > Configuration > Regional and language > Languages", enable the "URL" detection method, and configure it to "Path prefix"
*   for each enabled language, ensure to provide the corresponding standard "Path prefix language code" (don't leave it empty)
*   position the _Language switcher (User interface text)_ block in a region, anywhere you like

If you're also using some alternative translation methods (options of the _i18n_ module), there are some additional points you must pay attention to:

*   for each node where MMS is used, you MUST select the **Neutral language** in the "Language" field (or the lang switcher would deactivate any lang other than the specified one)
*   for each block where MMS is used, you MUST **keep unchecked all the proposed languages** in the "Languages" part of "Visibility settings"

</section>

<section>

#### User interface

While _MMS_ fundamental work is to interpret the "multi" parts of text found to render it in the current language when displaying public pages, it also manages how these parts are presented to the user when it is creating or updating nodes or blocks contents, their titles, and so on.  
At this moment the user must be able to see and modify all the different translations of the same text: this is provided by the MMS widgets.

*   **"long-text" fields** (such as body), which represent quantitatively the largest part of text and are input through `< textarea >` elements, may contain a lot of (even complex) HTML structures: it's why they're usually processed through a wysiwyg editor. So for them _MMS_ includes a _CKEditor_ plugin that can be activated for any text format (see [Using with _CKEditor_](#ckeditor)).

_CKEditor_

*   **all other text fields** (including "text", "link" and so on) are presented by Drupal through simple `< input type="text" >` elements. In this case:
    *   when an element contains only raw text, a "Use MMS template" link is proposed. When clicking this link:
        *   the element content is automatically normalized, i.e. formatted with the complete set of currently defined languages
        *   the original text is affected to the site main language, or to the currently selected language, or to a user-choosen language (see ["Multify" process](#advanced-entry-multi))
        *   the show/entry widget is displayed as described below
    *   when an element is already in MMS format, with language blocks for each of the currently defined languages, the widget is activated and offers displaying each language part when hovering, as well as the ability to input the different translations in dedicated cells. A "Drop MMS format" link is available, which allows to turn back to a single-language content if desired
    *   when an element is already in MMS format, but does not yet contains all the currently defined languages (situation for a pre-existing text, when a new language has just been defined), a block is automatically added for the missing language
    *   each entry area has its own changes history, available during the whole working process for the current form: so you can cancel/repeat all changes, independently for each areaThis way the user remains free to normalize input or not (may be keeping only a limited set of defined languages), while he has an easy way to update when a new language is added to the site.
*   by extension this behaviour is also available for texts which are not really fields, such as **field labels**, **node or block titles**, **menu links**, **vocabulary names** and **taxonomy terms**, **content types** definitions...

</section>

<section>

#### Advanced configuration

MMS offers a wide range of configuration options, divided into three tabs devoted respectively to the entry, rendering, and management fees. Two additional tabs allow, one to return to the default configuration for all or part of the options, the other to manage the translation of the user interface.

*   ##### DATA ENTRY tab

    *   ###### USER INTERFACE OPTIONS group

        *   Language selection behaviour.  
            Each input area includes a language selector, local to this area: hovering a language mark makes the corresponding content to display, clicking it opens the entry area in the choosen language.  
            You can define if a language selection applies only to the current area, or is propagated to all input areas in the the page (default value)
        *   Plain text input possibility.  
            By default each entry area is in the form of the MMS multilingual widget, which offers maximum comfort by hiding the underlying "multi" syntax. However it may be useful in some cases to provide direct access to plain text, especially when importing texts from a CMS such as _SPIP_.  
            In the case of a "text-long" area handled with CKEditor, this possibility is natively offered ("Switch to plain text editor" link, or "Source" button). For the other areas, an option allows to define if a button will be proposed to toggle to direct access mode, or if only the multilingual widget is available (default value)
    *   ###### "MULTIFY" PROCESS group

        When an area contains only text in a single language (for instance a text already existing when MMS was installed), turn to multilingual mode needs to decide to which language the existing text will be affected. Likewise if one wants to turn back to single language from an already multilingual area, it must be decided which language will be retained in the single-language text.  
        For both cases above, you can define if MMS will automatically use the site main language (default value), will automatically use the currently selected language, or will prompt user for choose a language

    *   ###### MULTILINGUAL INPUT WIDGET ACTIVATION group

        By default the multilingual input widget is activated for all input areas: this is generally expected for most of the forms. However this widget is of no interest in some areas (for instance a date or a number).  
        A list of CSS selectors registers here all occurrences of such areas in the most popular modules. You can enrich it depending on your needs and preferences.

*   ##### RENDERING tab

    *   ###### MISSING TRANSLATION RESPONSE group

        Inside a multilingual text area, a missing translation corresponds to several distincts cases:

        1.  there is no block for the required language (text existing before MMS was installed, or new language just defined)
        2.  there is a block for the required language, but it contains something like "...Language...", where "Language" is the native language name (area normalized by MMS in the absence of a text content)
        3.  there is a block for the required language, but it is empty (the author erased the block content)
        *   Cases #1 and #2 are always seen as missing translation and processed consequently (see next points).  
            An option allows to define if case #3 is also considered as missing translation (default value), or as voluntary absence of texte (no content will be rendered).
        *   When a translation is really missing (considering the above option), another option allows to define if it will be replaced by the corresponding text in the site main language (default value), or replaced by a customized message.
        *   The text that replaces a missing translation may be provided with a tip (title attribute) also customized, and presented through freely defined CSS.
    *   ###### PAGES CONTENT LOCALIZATION group

        By default, MMS localizes all multilingual contents of a page before displaying it. However most pages containing forms must escape this localization for typing multilingual texts.  
        A list of urls (which can be expressed as regular expressions) registers here all pages of this kind for the most popular modules. You may enrich it depending on your needs and preferences.

    *   ###### EXTRA LINEBREAKS group

        MMS allows you to include linebreaks in some short texts (such as a node title or a menu link), where they are normally not allowed by Drupal. By default, these linebreaks are merely rendered as spaces, as if they had not been entered.  
        A list of CSS selectors registers here the areas where they will be effectively rendered as linebreaks. You may enrich it depending on your needs and preferences.

*   ##### TOKENS tab

    MMS allows you to have alternative tokens that translates multilingual texts they address. Each token is cloned in two copies : first one will render text localized in the currently selected language, second one in the site main language.

    ###### RAW TOKENS CLONING group

    A list registers here the "raw" tokens (as opposed to field tokens, below) that must be cloned. You may enrich it depending on your needs and preferences.  
    A token such as _[type:token]_ provides the clones _[type:mms-token]_ and _[type:mms-native-token]_.

    ###### FIELD TOKENS CLONING group

    A list of checkboxes registers here all the field types currently defined. You may check the types which must cause related fields to be cloned.  
    A token such as _[node:field_myfield]_ provides the clones _[node:mms-field_myfield]_ and _[node:mms-native-field_myfield]_

*   ##### DEFAULT VALUES tab

    A list of checboxes registers here all options of the three preceding tabs. Launching execution makes each of the checked options to be reset to their default values.

*   ##### UI TRANSLATIONS tab

    ***

</section>

<section>

#### Using with _CKEditor_

With the _CKEditor_ module, you can benefit from improved input method which gets you rid of the above syntax and automatically offers input areas dedicated to each of the languages defined for the site.  
For this to work:

*   your version of _CKEditor_ must include the _Widget_ plugin (you may install it from the _CKEditor_ builder at !CKEditorBuilderLink)
*   in the _CKEditor_ configuration, for each profile where you want to allow it, in the "EDITOR APPEARANCE" group:
    1.  in the "Tools bar" section, add the "MMS" button to the tools bar
    2.  in the "Plugins" section, check "MMS" in the list of plugins to be activated
*   then with this profile any text field part where the "multi" syntax is used automatically displays a "MMS" group, with a subgroup inside for each defined language
*   at any time you may click the "MMS" button in the tools bar to create a new empty "MMS" group
*   note that only text fields (or blocks text) can be entered through _CKEDITOR_: in views, and in nodes or blocks titles, you still must use the "multi" syntax, or the improved interface offered by the integrated widget (as of 7.x-2.0)

</section>

<section>

#### Using with _Pathauto_

With the _Pathauto_ module, if you have introduced "multi" syntax in the node titles, you may use the `[node:mms‑native‑title]` token to generate URL aliases, which will be localized using the **site default language**.  
WARNING: using the `[node:title]` token would generate aliases from the **raw** title, resulting in something like `multienmy‑titlefrmon‑titremulti`!

</section>

<section>

#### Using with _Views_

With the _Views_ module, you can use the "multi" syntax inside of the texts you enter in the definition forms of a view.  
They will be rendered like explained above, in the views summary, in the previews, and of course in the pages where they are included.

</section>

<section>

#### Syntax (for raw text mode input)

The following describes the raw internal structure which makes the MMS mechanism to work, as initially designed by its predecessor, the _Multilang_ module.  
With MMS you can totally ignore the "multi" syntax. However you can continue to use it at your convenience, as part of a direct entry in raw text mode, especially in case of migration from _SPIP_.  
To enter text in this mode, you must:

*   in areas handled with _CKEditor_, click the "Switch to plain text editor" link or the "Source" button of _CKEditor_
*   in any other area, click the toggle button "MMS" at the right bottom of the form: then all the MMS widgets disappear and let you see the original entry areas, with their raw content  
    _NOTE: this toggle button is available only if you have activated the corresponding configuration option (see [Plain text input possibility](#advanced-entry-iu))_

When entering data in a text area, you may insert multilingual pieces of text by enclosing them between `[ multi ]` and `[ /multi ]` tags.  
Such a piece of text is a "multi" _segment_, which may contain a number of "multi" _blocks_, each representing the desired content translated in a given language, like `[language‑mark]…content…`, where:

*   `language‑mark` is the involved language code, such as `en`, `fr`, `es`…
*   `…content…` is the translated content

Example:  

> `[ multi ]  
> [ en ] This is an english text  
> [ fr ] Ceci est un texte en français  
> [ /multi ]`

Any spaces, newlines, line-breaks or paragraph-breaks are ignored when they are located just after the opening tags, juste before the closing tags, and just around the language-marks. In other words, each text block is rendered trimmed.

</section>

<section>

#### Tips

1.  Which language code is used to render depends on the lang part of the current URL (such as "en" in `http://example.com/en/…`), which is generally defined by how the lang switcher is currently set. If no language is currently defined (so Drupal language is empty), the site lang is used.  
    As a fortunate side effect, at any moment you may deactivate the lang switcher, and all contents including the "multi" syntax are simply rendered in the site lang.  
    CAUTION, though: at the time this document is written (Drupal 7.34), deactivate the lang switcher seems to drop already registered vocabulary terms translations!
2.  If a "multi" segment does not contain translation for the current lang, the available text in the site lang will be rendered instead. However you may configure MMS in order to not display anything at all in this case(see [Missing translation](#advanced-rendering-fallback))
3.  In order to allow a simple migration of contents from the Spip CMS, an alternative syntax is also accepted, using HTML-fashion tags such as `< multi >` and `< /multi >`, rather than `[ multi ]` and `[ /multi ]` (but language marks keep using square brackets, like in `[ en ]`).  
    You may also use this alternative syntax when manually entering text (when not in _CKEditor_ nor in MMS widget).
4.  Becareful when directly importing data from an external source: due to the internal rules of the _HTML purifier_ plugin, _CKEditor_ breaks the _MMS_'s automatic recognition of language blocks when they include `< div >` tags. You may consider to replace them by `< section >` tags.  
    Another solution could be to deactivate the _HTML purifier_ plugin, so the <div> tags can be used, but this is not recommended, for general security reasons.

</section>

<section>

#### Localization

Because of its mission to integrate multiple languages in the same container, the _MMS_ module does not conform to the standard Drupal localization system: in this domain, it is self-sufficient and embeds all of its own translations, written with the "multi" syntax.  
All these translations (except the help text you are reading now) are gathered in the file `mms.data.inc` : if it does not include a version in your favorite language you can easily add it using the tools available at the user interface translation page !MMSUILink.  

Due to its size, the help text is not included in the `mms.data.inc` file. Instead it resides in a set of independent files (one for each language) like `mms.help._LANGUAGE_.inc`, where the contents are pure HTML.  
So to add a version of the help text in your favorite language, say XX, you have to create a new file named `mms.help._XX_.inc` and located in the `sites/all/mms` folder. Please be careful to keep unchanged the original HTML structure, especially the sections headings with their `class` and `id` attributes.

_NOTE FOR ENGLISH SPEAKERS: the creator of this module is not fluent in English, so he is unsure of the quality of writing. **All corrections and improvements are welcome.**_

</section>