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.
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 filesite.properties
and enter the following text:first.name = First name last.name = Last name
In the same directory, create a resource file
site_fr.properties
and enter the following text:first.name = Prénom last.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 toPr\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 Codes for the Representation of Names of Languages.
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, 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 fileSiteModification.java
and enter the following text:
import com.psddev.cms.db.Site; import com.psddev.dari.db.Modification; public class SiteModification extends Modification<Site> { SiteModification () {}; private Locale locale; public Locale getLocale() { return locale; } public void setLocale(Locale locale) { this.locale = locale; } }
This model adds the locale
field to the Site
model, making it visible on the Edit Site widget.
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 fileSignup.java
and enter the following text:
import com.psddev.cms.db.Content; public class Signup extends Content { private String firstName; private String lastName; /* Setters and getters */ }
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 fileSignup.hbs
and enter the following text:
<table> <tr> <td>{{firstNameLabel}}</td> <td><input type="text"/></td> </tr> <tr> <td>{{lastNameLabel}}</td> <td><input type="text"/></td> </tr> </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 fileSignup.json
and enter the following text:
{ "_template": "Signup.hbs", "firstNameLabel": "{{words(1)}}", "lastNameLabel": "{{words(1)}}" }
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 fileSignupViewModel.java
and enter the following text:
import com.psddev.cms.db.Site; import com.psddev.cms.view.ViewModel; import com.psddev.cms.view.PageEntryView; import com.psddev.cms.view.servlet.CurrentSite; import styleguide.content.article.SignupView; public class SignupViewModel extends ViewModel<Signup> implements SignupView, PageEntryView { @CurrentSite 1 private Site site; @Override public String getFirstNameLabel() { 2 ResourceBundle labels = getLabels(); String firstNameLabel = labels.getString("first.name"); return firstNameLabel; } @Override public String getLastNameLabel() { 3 ResourceBundle labels = getLabels(); String lastNameLabel = labels.getString("last.name"); return lastNameLabel; } private ResourceBundle getLabels() { 4 Locale locale = site.as(SiteModification.class).getLocale(); ResourceBundle resourceBundle = ResourceBundle.getBundle("i18n.site",locale); return resourceBundle; } }
Retrieves the requested site into a
| |
Returns the localized string for | |
Returns the localized string for | |
Returns the resource bundle that contains the localized strings. |
Running the view model displays the expected result.