Localizing published websites

Localizing a published website with Brightspot is similar to that for other Java-based web applications. In Brightspot’s MVVM paradigm, you need to—

Define resource files that contain key-value lookups for the localized labels.
Place the lookup and output mechanisms in the view model.
Insert label placeholders in the Styleguide files.

The steps in this section demonstrate localizing the following short form into French.

Localization example.svg

Step 1: Make a localization resource file

A localization resource file contains the key-value pairs for localized strings. As a best practice, place all your localization files in a single directory. The directory must be under /src/main/resources/.

Under /src/main/resources/i18n/, create a default resource file site.properties and enter the following text:
showLineNumbers
```
1first.name = First name
2last.name = Last name
```
In the same directory, create a resource file site_fr.properties and enter the following text:
showLineNumbers
```
1first.name = Prénom
2last.name = Nom de famille
```
Depending on your development or run-time environment, you may need to escape non-ASCII characters in the properties files. For example, in the previous file, Prénom is changed to Pr\u00e9nom using Java’s native2ascii utility.

For information about creating a properties file for localization, see Backing a ResourceBundle with Properties Files. In particular, the two letters before .properties in the file name must be a language code that Java recognizes. For a list of two-letter language codes, see List of ISO 639-1 codes.

Step 2: Add localization property to site

Localization is almost always done at the site level; if one page in a site appears in French, all other pages appear in French. As explained in Step 6 below, the view model determines in which locale to display content by reading a site’s locale field. Brightspot’s Site class does not include a locale field, so you need to add it using the Modification class.

Under /src/main/java/content/article/, create a file SiteModification.java and enter the following text:

showLineNumbers

1import com.psddev.cms.db.Site;
2import com.psddev.dari.db.Modification;
3
4public class SiteModification extends Modification<Site> {
5
6    SiteModification () {};
7
8    private Locale locale;
9
10    public Locale getLocale() {
11        return locale;
12    }
13
14    public void setLocale(Locale locale) {
15        this.locale = locale;
16    }
17
18}

This model adds the locale field to the Site model, making it visible on the Edit Site widget.

Adding the Locale field to a form

For additional information about extending classes such as Site, see Modifications.

Step 3: Create a signup model

Create a simple model that displays fields for first name and last name in a signup form.

Under /src/main/java/content/article/, create a file Signup.java and enter the following text:

showLineNumbers

1import com.psddev.cms.db.Content;
2
3public class Signup extends Content {
4
5    private String firstName;
6
7    private String lastName;
8
9    /* Setters and getters */
10}

Step 4: Create a template

Localization typically involves displaying a locale-specific string for each static label on the GUI. Continuing the example, create a Handlebars file that has a placeholder for each label on the form.

Under /styleguide/content/article/, create a file Signup.hbs and enter the following text:

showLineNumbers

1<table>
2    <tr>
3        <td>{{firstNameLabel}}</td>
4        <td><input type="text"/></td>
5    </tr>
6    <tr>
7        <td>{{lastNameLabel}}</td>
8        <td><input type="text"/></td>
9    </tr>
10</table>

Step 5: Create a data file

Create a data file that has a placeholder for each label in the form.

Under /styleguide/content/article/, create a file Signup.json and enter the following text:

showLineNumbers

1{
2  "_template": "Signup.hbs",
3  "firstNameLabel": "{{words(1)}}",
4  "lastNameLabel": "{{words(1)}}"
5}

Step 6: Create a localized view model

The view model includes the logic for retrieving localized strings based on the requested site’s locale.

Under /src/main/java/content/article/, create a file SignupViewModel.java and enter the following text:

showLineNumbers {9,13,20,26}

1import com.psddev.cms.db.Site;
2import com.psddev.cms.view.ViewModel;
3import com.psddev.cms.view.PageEntryView;
4import com.psddev.cms.view.servlet.CurrentSite;
5import styleguide.content.article.SignupView;
6
7public class SignupViewModel extends ViewModel<Signup> implements SignupView, PageEntryView  {
8
9    @CurrentSite
10    private Site site;
11
12    @Override
13    public String getFirstNameLabel() {
14        ResourceBundle labels = getLabels();
15        String firstNameLabel = labels.getString("first.name");
16        return firstNameLabel;
17    }
18
19    @Override
20    public String getLastNameLabel() {
21        ResourceBundle labels = getLabels();
22        String lastNameLabel = labels.getString("last.name");
23        return lastNameLabel;
24    }
25
26    private ResourceBundle getLabels() {
27        Locale locale = site.as(SiteModification.class).getLocale();
28        ResourceBundle resourceBundle = ResourceBundle.getBundle("i18n.site",locale);
29        return resourceBundle;
30    }
31
32}

9. Retrieves the requested site into a Site variable. The annotation @CurrentSitereturns null for Brightspot's global site. Therefore, when creating localized sites, ensure editors publish to a site other than global.
13. Returns the localized string for first.name.
20. Returns the localized string for last.name.
26. Returns the resource bundle that contains the localized strings.

Running the view model displays the expected result.

View model showing localization

See also:

Localization