URL Translation Module

Edition

Incubator (services)

Issues

Git

Latest

6.2.8

Compatible with Magnolia 6.3, 6.2, 6.1, 5.7, 5.6.

The Magnolia URL Translation module builds off the previous Urltrans Module. The idea of the module is to provide a way to translate the page names in a single-tree-multi-language website.

Delivery endpoint translation support was added in 6.2.5 with the additional rest module.

See enabling multilanguage content for how to set up this type of website. Using the translation module together with your translated website you can internationalize your URLs.

This module is at the INCUBATOR level.

In order for page translation to work a domain configuration is requried on the site definition.
The class URLTranslator uses a query to locate the translated page names. Very deep hierarchies could see performance impacts.
Version 5.6.1 should be avoided due to MURLTRANS-6.
You cannot use folder nodes at the root of the workspace. The top level node must be of mgnl:page type.
Testing on the author instance can be tricky when using EE Pro or DX core. If possible do not install the module on the author instance. Without a configured domain in the site definition the multisite module will prefix URIs with the name of the site definition. In most cases this will end up as a 404.
This module is meant for use on the public instance to translate urls. If installed on author you will run into problems in the page editing when switching languages (404s). The only thing that needs to be done on the author instance is the capture of the translated page names. This is a pure dialog configuration and nothing more than page level content. If you installed the module on author already you can disable the filter and switch back the link transformers.
- /server/filters/cms/urltrans@enabled -→ false
- /server/rendering/linkManagement@class -→ info.magnolia.multisite.MultiSiteLinkTransformerManager
- /server/rendering/linkManagement/transformers/absolute@class -→ info.magnolia.link.AbsolutePathTransformer

Installing with Maven

Maven is the easiest way to install the module. Add the following to your bundle:

Magnolia 6.2
Magnolia 6.1
Magnolia 5.7

<dependency>
  <groupId>info.magnolia.i18n</groupId>
  <artifactId>magnolia-url-translation</artifactId>
  <version>6.2.8</version>
</dependency>

<!-- Rest module is optional -->
<dependency>
  <groupId>info.magnolia.i18n</groupId>
  <artifactId>magnolia-url-translation-rest</artifactId>
  <version>6.2.8</version>
</dependency>

<dependency>
  <groupId>info.magnolia.i18n</groupId>
  <artifactId>magnolia-url-translation</artifactId>
  <version>6.1.1</version>
</dependency>

<dependency>
  <groupId>info.magnolia.i18n</groupId>
  <artifactId>magnolia-url-translation-multisite</artifactId>
  <version>6.1.1</version>
</dependency>

<dependency>
  <groupId>info.magnolia.i18n</groupId>
  <artifactId>magnolia-url-translation</artifactId>
  <version>5.6.2</version>
</dependency>

<dependency>
  <groupId>info.magnolia.i18n</groupId>
  <artifactId>magnolia-url-translation-multisite</artifactId>
  <version>5.6.2</version>
</dependency>

Usage

By default the module will expect to find the translated names of pages in an internationalized field called name. This requires the page level dialog to be modified so that editors may be able to set the property.

Configuration

For those requiring personalized pages to have translated names the module offers the option to configure the query so that variant pages can be found. You will also need to store your translations on a property other than the default name.

In the module url-translation you will find the properties:

Property Description

nodeType

optional, defaults to `mgnl:page`

Defines the type for the query.

Changing this value can affect performance.

propertyName

optional, defaults to `name`

Defines the name of the property where the translation can be found.

Example

modules:
  url-translation:
    config:
      nodeType: mgnl:page (1)
      propertyName: name (2)

1	`nodeType`
2	`propertyName`

Page level dialog

This module expects to find the translated names of pages in an internationalized field defined by module level configuration propertyName.

Consider an example using the MTK2 page dialog as a base: /mtk2/dialogs/pages/basic.yaml

form:
  properties:

    # Here we add the name field to the page properties dialog.
    # Don't forget to place the property in the layout below.
    name:
      $type: textField
      i18n: true
      label: Name

    title:
      $type: textField
      i18n: true
    navigationTitle:
      $type: textField
      i18n: true
    hideInNav:
      $type: checkBoxField
    windowTitle:
      $type: textField
      i18n: true
    abstract:
      $type: textField
      rows: 5
      i18n: true
    keywords:
      $type: textField
      rows: 3
      i18n: true
    description:
      $type: textField
      rows: 5
      i18n: true
    noCache:
      $type: checkBoxField
  layout:
    $type: tabbedLayout
    tabs:
      - name: tabMain
        fields:
          - name: name
          - name: title
          - name: navigationTitle
          - name: hideInNav
          - name: windowTitle
          - name: abstract
      - name: tabMeta
        fields:
          - name: keywords
          - name: description
          - name: noCache

SEO considerations

Added in 6.2.5

Language-specific content is typically requested using a locale selector. Whether or not the translated page names are sent with the request is not relevant to the system. For example, it’s possible to request German content of the travel demo by adding the /de selector to the request URI.

English content: https://demopublic.magnolia-cms.com/about.html
German content: https://demopublic.magnolia-cms.com/de/about.html

This creates a scenario where the language-specific travel demo content can have multiple valid request URLs since the German content could be requested using the default language and the translated language.

Blocking default language requests (i.e. returning a 404) is achieved by reconfiguring the filter. Two settings are required:

A bypass for the default language using a LocaleVoter configuration.
Add blockDefaultUrls set true

Changelog

Version Notes

Version	Notes
`6.2.8`	Changelog
`6.2.7`	MURLTRANS-45
`6.2.6`	MURLTRANS-42 MURLTRANS-43 MURLTRANS-44
`6.2.5`	MURLTRANS-24 MURLTRANS-37 MURLTRANS-39
`6.2.4`	MURLTRANS-25 MURLTRANS-30 MURLTRANS-31 MURLTRANS-32 MURLTRANS-33 MURLTRANS-35
`6.2.3`	MURLTRANS-20
`6.2.2`	MURLTRANS-16
`6.2.1`	MURLTRANS-15
`6.2`	MURLTRANS-12
`6.1.1`	Use the aggregation state to retrieve locale.
`6.1`	MURLTRANS-8
`5.6.2`	MURLTRANS-6
`5.6.1`	MURLTRANS-3
`5.6`	MURLTRANS-1

6.2.8