Localising Sites in Unify

From VYRE

Jump to: navigation, search
Localising Sites in Unify
Flags of world
Unify Tutorial Series
Difficulty Level Intermediate
Prerequisites Adding Content
This tutorial assumes that you already have a site set up with content items that are waiting to be localised. If not please ensure you get the system into this state. This can be achieved by completing the basic tutorial series.

Contents

Localising Sites in Unify

Objective

In this tutorial we're going to translate a site into another locale, offering localised text, content and URL paths. For this tutorial we are only going to add information for one extra "secondary" locale, but the process will be identical for multiple locales. VYRE Unify can handle all locales supported by Java. Custom Java web applications deployed in the same tomcat instance as Unify that can handle Java localisation will automatically respond to the locale change request. It is worth noting that with each new version of Java, new locales are supported.

Enabling Extra Locales

Before we can start localising our site, we must first allow the site to respond to locale change requests. This is handled in the site edit dialogue. In this example, we're going to allow Unify to respond to French (France) locale change requests.

  1. Click your site globe to open the site edit dialogue.
  2. Tick the box entitled “Allow users to change site locale with query parameter "site_locale".” This will display a multiple select box with allowed and not allowed locales.
  3. Find French (France) in the list, move into the allowed box and save.

This now instructs Unify to serve the French locale when requested. We can send the request to Unify either by binding a domain name to a specific locale or by passing the locale code as a value to the site_locale URL parameter.

E.G. http://www.mysite.com/mypage/?site_locale=fr_FR

Localising Text

Before we can test out our French locale we need to create some localised text. Localised text is handled by creating locale “keys”. These keys are then linked to multiple translations, one per locale, that the system will display when requested.

For example, we can create a key called “test.hello”. We can then create an English version with the value “Hello” and a French version with the value “Bonjour”. The system will then serve either the English or French version depending on the locale being requested.

  1. Open the configuration module, expend System Configuration and select Localizations.
  2. Click the “Create” button, enter a key describing what your text will do an save.

  3. Creating a localisation key with values


  4. Select the French (France) locale from the Locale select box and click “Add Locale”
  5. You should now have two boxes with “Not Yet Translated” in them. One for the French (France) and one for the default locale of your site (English by default). Enter the translations in the boxes and click save.
  6. Add a static code portlet to a page on your site and in it enter the following text: $bundle.translate('test.hello') where 'test.hello' is the key you created earlier.
  7. Save the portlet, deploy and view in the front end.
  8. The system should translate the locale into the default locale of the site. If there is no locale you'll see your key wrapped in question marks.

  9. Append site_locale=fr_FR to your URL as a query string EG http://my.site.com/test/?site_locale=fr_FR
  10. Your text should be translated into the French version.

It is also possible to force a domain name to serve up a specific locale This can be useful if you have multiple sub domains such as fr.test.com and es.test.com and you want them to serve up French and Spanish content respectively. To do this:

  1. Click the site globe that would want to apply the domain names
  2. From the Actions menu, select “Add Domain Name”
  3. Enter your domain name, and choose the locale you would like the site to serve.

Localising Content

In Unify, localising content can be handled independently to localising text, and it is not a requirement, when localising text to localise content. The localisation of data happens on a store by store basis and is disabled by default. To enable localisation of a specific store, edit the store, and as with sites, select the locales you would like to use and move them into the “Secondary collection languages” window.

Creating a Localised Item

In Unify, we call the un-localised item (that which is in the default locale) the primary item. All localised versions of that item are referred to as secondary items.

Using the vyre4 back end
  1. Open your localisation enabled store
  2. Find the item for which you would like to create a localised version, and click the edit link
  3. From the Localization.. menu, click “Request Localization”. This tags the items as one that is localised. You will be warned that “This item has incomplete secondary localizations” because we are yet to create a fr_FR version.
  4. From the Localization.. menu again, click create French (France) version, complete the create item dialogue, check the item in and activate it. You will see an orange alert box explaining that “This item is a secondary localization item”.
  5. Note that Unify treats secondary localised items no differently to primary items, and lists them in the usual way.

    Search Results porlet XML with localisations enabled

    To view the localised items:

  6. Add a search-results portlet to a page, and configure it to bring back all items from your store (or sensible search that will return the recently created localised items).
  7. Tick the box entitled “Retrieve localizations of each item” save and examine the generated XML.


In this instance you'll notice that VYRE Unify returns the secondary localised items alongside the primary ones treating them as independent items. As we've enabled it, each item will also contain a localization node, which contains multiple locale nodes, one for each localised version as can be seen in the image.

Using the front end to create items

If you examine the XML generated above you'll notice that each locale node, contains either a create-link or edit-link node depending on whether an item in that locale exists. This node contains a a portion of a URL that should be passed to the create / edit page to allow the creating or editing of a localised versions.

EG – To construct a URL to create a French localised version of an item: <a href = “create/{locale[id='fr_FR']/create-link}”> and to edit an existing French localised item: <a href = “edit/{locale[id='fr_FR']/edit-link}”>

As different sites and concerns might need different requirements regarding localization, VYRE Unify does not force any particular way but leaves this open to the developer to determine programmatically how the system should respond to locale changes. Whilst it would be beyond the scope of this tutorial to cover all potential rules. I will demonstrate two common opposing requirements that might be used on the same site, or even on the same page. These are: 1) Display content in the current (secondary) locale and if the item is not present fall back to the primary localised item 2) Display content in the current (secondary) locale and if the item is not present do not fall back.

1) Falling back to the primary locale

This is a common requirement. Often with a site, we don't have complete localisation of all items. For example we might be modeling a library or book store. There might exist many books that have been translated into other languages and we would by default want to serve books in the end users locale, but there will be times when there is only a book in the default locale and in this situation we would want to display the primary localised book.

To accomplish this we must first ensure that our search results XML contains both the current locale items and the site default locale. We can make locale related searches by using the 'locale' keyword.

  1. First, create a saved search that only brings back the default locale of the site. Currently there is no dynamic variable to define this, so it must be hard coded. If your default locale is 'en' create saved search with "locale:en"
  2. Apply the saved search to a search results portlet and tick the “retrieve localised version of items” box
  3. This would then bring us back all 'en' versions of items, with their localised version. It would then be up to the XSL developer to display the localised version, if existing, or fall back to the primary localised version.

2) Not falling back to a default

This method is somewhat easier and lighter. In this method we would construct a saved search to only return the current locale. To do this, we can use the $renderLocale variable. EG – locale:$renderLocale. Then any item that does not exist in the current locale will not be returned.

Localised Paths

Unify also offers the ability to localise paths. When you create or edit a page on a site that allows other locales, the system will offer fields from within the page edit dialogue for entering localised paths values. Unify will respond to any of the localised paths not just the path relevant to the current locale.

Note, it is only possible to create a localised path for a page if the site is allows the specific locale and it's parent page also has an entry for that locale.


Other areas that can be localised

There are other areas of VYRE Unify that can be localised. These work by applying localisation keys to specific areas. These are:

  • Attribute presentation rules
  • Taxonomy category names
  • Custom user profile property names
  • Page titles, names and descriptions.
  • Login portlet labels
Personal tools