It’s very easy to get translations in back-end code — either Razor views or .cs files — by simply calling to Sitecore.Globalization.Translate.Text(). But what about JavaScript widgets? There we have several options:
- Item Web API results in overhead and is hard to use without additional implementation.
- StringDictionary embeds values right in HTML and needs to be configured accordingly.
- Injecting translated text into .js components via HTML tags has the same drawbacks as StringDictionary.
All these options are cumbersome and inconvenient.
I will show you a convenient way to have Translate.Text() right in JavaScript! The idea is to use a JavaScript dictionary object in our .js widgets/components. To achieve the goal we need the following:
- Serialize dictionary values into .json files
- Implement Dictionary.js
Let’s start coding!
Serializing the dictionary into .json files
Serializing the whole dictionary creates one .json file per language in a temp folder. The file’s name looks like “dictionary.{language}.json”, e.g. “dictionary.fr-CA.json”. The dictionary is serialized each time we perform a site publish or when we publish a Dictionary root item or its descendants.
2 | using Newtonsoft.Json.Converters; |
5 | using Sitecore.Data.Events; |
6 | using Sitecore.Data.Items; |
7 | using Sitecore.Data.Managers; |
8 | using Sitecore.Diagnostics; |
10 | using Sitecore.Globalization; |
12 | using Sitecore.Publishing; |
14 | using System.Collections.Generic; |
18 | namespace Company.Project.EventHandlers |
20 | /// <summary> |
21 | /// Creates dictionary .json files on publish events |
22 | /// </summary> |
23 | public class SerializeDictionaryToJson |
25 | private static ID DictionaryFolderTemplateID = new ID("{267D9AC7-5D85-4E9D-AF89-99AB296CC218}"); |
27 | public void OnPublishEnd(object sender, EventArgs args) |
29 | var sitecoreArgs = args as SitecoreEventArgs; |
30 | Assert.IsNotNull(sitecoreArgs, "The parameter 'sitecoreArgs' is null"); |
32 | var publisher = sitecoreArgs.Parameters[0] as Publisher; |
33 | Assert.IsNotNull(publisher, "The parameter 'publisher' is null"); |
35 | var rootItem = publisher.Options.RootItem; |
37 | if (ShouldSearializeDictionary(rootItem)) |
39 | SerializeDictionaryToJsonFiles(); |
43 | public void OnPublishEndRemote(object sender, EventArgs args) |
45 | var remoteEventArgs = args as PublishEndRemoteEventArgs; |
46 | Assert.IsNotNull(remoteEventArgs, "The parameter 'remoteEventArgs' is null"); |
49 | var rootItemID = remoteEventArgs.RootItemId; |
50 | if (rootItemID != default(Guid)) |
52 | var db = Database.GetDatabase("web"); |
53 | rootItem = db.GetItem(ID.Parse(rootItemID)); |
56 | if (ShouldSearializeDictionary(rootItem)) |
58 | SerializeDictionaryToJsonFiles(); |
62 | private bool ShouldSearializeDictionary(Item rootItem) |
64 | return rootItem == null || |
65 | rootItem.TemplateID == DictionaryFolderTemplateID || |
66 | rootItem.TemplateID == TemplateIDs.DictionaryEntry || |
67 | rootItem.ID == ItemIDs.Dictionary; |
70 | public void SerializeDictionaryToJsonFiles() |
72 | var db = Database.GetDatabase("web"); |
73 | var languages = LanguageManager.GetLanguages(db); |
75 | foreach (var language in languages) |
77 | var values = GetDictionaryValues(db, language); |
78 | CreateDictionaryJsonFile(values, language); |
81 | Log.Info("Dictionary has been serialized to json files successfully.", this); |
84 | public void CreateDictionaryJsonFile(IDictionary<string, object> values, Language language) |
86 | var json = JsonConvert.SerializeObject(values, new KeyValuePairConverter()); |
87 | var filePath = $"{TempFolder.Folder}/dictionary.{language.Name}.json"; |
88 | FileUtil.WriteToFile(filePath, json); |
91 | public IDictionary<string, object> GetDictionaryValues(Database db, Language language) |
93 | IDictionary<string, object> dictionary = new ExpandoObject(); |
95 | using (new LanguageSwitcher(language)) |
97 | var root = db.GetItem("/sitecore/system/Dictionary"); |
99 | var items = root.Axes.GetDescendants() |
100 | .Where(i => i.TemplateID == TemplateIDs.DictionaryEntry); |
102 | foreach (var item in items) |
104 | var key = item[FieldIDs.DictionaryKey]; |
105 | dictionary[key] = item[FieldIDs.DictionaryPhrase]; |
The last thing is to plug SerializeDictionaryToJson.cs to publish:end and publish:end:remote events by using patch config.
1 | <?xml version="1.0" encoding="utf-8"?> |
2 | <configuration xmlns:patch="http://www.sitecore.net/xmlconfig/"> |
3 | <sitecore> |
5 | <event name="publish:end"> |
6 | <handler type="Company.Project.EventHandlers.SerializeDictionaryToJson, Company.Project" method="OnPublishEnd"/> |
8 | <event name="publish:end:remote"> |
9 | <handler type="Company.Project.EventHandlers.SerializeDictionaryToJson, Company.Project" method="OnPublishEndRemote"/> |
11 | </events> |
12 | </sitecore> |
13 | </configuration> |
Implement Dictionary.js
I assume you are using a module loader; in my example it’s require.js. Dictionary.js loads the proper .json file only once per page based on the current context language and provides translation.
1 | define(["jquery"], function ($) { |
3 | Dictionary._instance = null; |
9 | Dictionary.prototype.translate = function (key) { |
10 | return this.values[key] || key; |
13 | Dictionary.prototype.getContextLanguage = function () { |
14 | return $('meta[http-equiv="content-language"]').attr("content"); |
17 | Dictionary.prototype.loadValues = function () { |
18 | var language = this.getContextLanguage(); |
19 | var valuesUrl = "/temp/dictionary." + language + ".json"; |
22 | $.ajax({ cache: false, async: false, url: valuesUrl }) |
23 | .done(function (data) { |
24 | this.values = Object.freeze(data); |
27 | console.error("Couldn't load dictionary values"); |
31 | Dictionary.getInstance = function () { |
32 | if (Dictionary._instance == null) { |
33 | var dictionary = new Dictionary(); |
34 | dictionary.loadValues(); |
35 | Dictionary._instance = dictionary; |
37 | return Dictionary._instance; |
40 | return Dictionary.getInstance(); |
How to use Dictionary.js
In this sample, our SearchBox widget utilizes translations based on the current page language.
1 | define(["Dictionary"], function (dictionary) { |
3 | function SearchBox(options) { |
4 | this.noResultsFoundText = dictionary.translate("NoResultsFound"); |
dictionary.en.json snippet
1 | { ... "NoResultsFound": "Sorry, we have no content matching your criteria." ... } |
dictionary.fr-CA.json snippet
1 | { ... "NoResultsFound": "Désolé, nous avons aucun contenu ne correspond à vos critères." ... } |
Dictionary.js features
- Doesn’t inject values into HTML.
- Doesn’t impact SEO.
- Lazy loading.
- No need to configure.
- Small overhead: serialized .json file is 13kB for 300 items in real-world application.
- Can be loaded from browser’s cache.
Might want to plug that into “publish:end:remote” as well otherwise the file will not be created on the CD servers.
> Thanks for pointing me out, you’re absolutely right. I will update the post in case of CD.
That’s very similar to a way how translation is done in Experience Editor(look at TranslationUtil.js).
define([“sitecore”], function (Sitecore) {
var translationUtils = {
keys: {
},
translateText: function (key) {
return Sitecore.Resources.Dictionary[key];
},
translateTextByServer: function (key) {
…
},
};
return translationUtils;
});
TranslationUtil.js looks ‘similar’ but:
TranslationUtil.translateText uses values injected in html and StringDictionary needs to be configured for each page.
TranslationUtil.translateTextByServer can be used in Experience Editor context only and sends one ajax per ‘key’ which results in request/response overhead.
The approach described in the post uses more flexible way without needs to configure, injections and so on.
Pingback: Sitecore Dictionaries Best Practices | Sitecore notes - Stelio Di Bello