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 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 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 private Site site; @Override public String getFirstNameLabel() { ResourceBundle labels = getLabels(); String firstNameLabel = labels.getString("first.name"); return firstNameLabel; } @Override public String getLastNameLabel() { ResourceBundle labels = getLabels(); String lastNameLabel = labels.getString("last.name"); return lastNameLabel; } private ResourceBundle getLabels() { Locale locale = site.as(SiteModification.class).getLocale(); ResourceBundle resourceBundle = ResourceBundle.getBundle("i18n.site",locale); return resourceBundle; } }
-
Retrieves the requested site into a
Site
variable. The annotation@CurrentSite
returns null for Brightspot's global site. Therefore, when creating localized sites, ensure editors publish to a site other than global. -
Returns the localized string for
first.name
. -
Returns the localized string for
last.name
. -
Returns the resource bundle that contains the localized strings.
-
Running the view model displays the expected result.
See also: