Saturday, June 2, 2012

How to add a new supported language in CQ / WEM

Use case: 

  • You want to add new language to CQ
  • Change display language options in translator grid
  • Change language name and default countries 


You can access translator UI in CQ with following URL http://<HOST>:<PORT>/libs/cq/i18n/translator.html

Create new language location for Dictionary

Go to CRXDE lite (or your favorite JCR browser) and add this structure (assuming /apps/myproject/i18n as a typical location for custom apps):
/apps/myproject/i18n [sling:Folder]
    - de [nt:unstructured] [mix:language]
        + jcr:language = de
    - fr [nt:unstructured] [mix:language]
        + jcr:language = fr
Then reload the translator and the path /apps/myproject/i18n should show up in the drop-down at the top.
Note: the translator will only save translations for languages that are actually present underneath the path (e.g. /apps/myapp/i18n), others will be skipped.

Change List of Languages Display in Grid

To change what languages are shown in the translator's grid, create a multi-value string property /etc/languages/languages (node structure must be created), containing the iso language codes (e.g. ["de", "fr", …]). The default is hard coded in the translator and maps the ootb CQ languages: ['de', 'fr', 'it', 'es', 'ja', 'zh-cn']

Add supported language in WCM

  • You need to overlay/overwrite /libs/cq/security/widgets/source/widgets/security/Preferences.js to change the list of available languages (used in security admin)
  • and overlay /libs/cq/security/content/tools/userProperties (inside change language list under items/common/items/lang/options - similar dialog to Preferences.js) (used for user drop-down in the top right on admin consoles)
  • Then you need to add the new language somewhere in the repo, e.g. /apps/yourapp/i18n, following the layout as under /libs/wcm/core/i18n (see also the above section on the translator UI). Stuff under /libs must not be changed!
Here is a sample package:
  • adds /apps/test/i18n with translation of "New..." in zh-cn ("simplified") and zh-tw ("traditional") languages
  • overlays /apps/cq/security/content/tools/userProperties and /apps/cq/security/widgets/source/widgets/security/Preferences.js to add the zh-tw language
  • to check, set the current user's language to "Traditional Chinese" and look in the siteadmin: the first button in the toolbar should now be "traditional" instead of "New..."
change language name and default country 

Note: since 5.5 load 21
This means:
  • language titles
  • country names
  • default countries (for codes like "en", "de", etc.)
A language list is stored under /libs/wcm/core/resources/languages. It can be overlayed by copying it to /apps/wcm/core/resources/languages and changing or extending the list there. If you do so, also change the configuration of the language manager set langmgr.list.path = /apps/wcm/core/resources/languages at 

The default countries, which come into play when resolving the country for a language code such as "en" ("en_GB" would be such a default country), and in turn for displaying flags in the UI, are configured in this list as well. A property defaultCountry on a language node must contain the full code, such as "ja_jp", which would define "jp" as default country for "ja".

Information is provided by Alexander Klimetschek  from Adobe. Many thanks to him. 


  1. Nice blog. A lot of useful articles here.

    Are you able to edit the language values through the i18n/translator? I can click and change them and then save, but when I click Reset & Refresh, the original value remains. Any ideas?

    1. Yes. You should be able to edit value from translator. Make sure that you click on save after change. Let me know if that is not working. I just tested and it works for me.

    2. I have the same problem. Clicking on "Save" does not seem to have any effect.
      Although the POST is answered with {success : true}.

  2. There is an error in /libs/cq/i18n/translator/translations/POST.jsp which causes changes always to be stored in /libs/wcm/core/i18n.

    Replace lines 720 and 721 with:

    boolean isDelete = Arrays.asList(slingRequest.getRequestPathInfo().getSelectors()).contains("delete");
    JSONObject obj = new JSONObject(new ReaderJSONTokener(slingRequest.getReader()));

    if (obj.has("path")) {
    this.path = obj.get("path").toString();
    if (this.path == null || this.path.isEmpty()) {
    this.path = "/libs/wcm/core/i18n";

    Delete lines 760 and 762

    1. Thanks a lot Linda for sharing this.

    2. Is there any official documentation on this error?

    3. Unfortunately there is no documentation. However you can open a daycare ticket for this issue.


  3. can you please elaborate on the section "Change List of Languages Display in Grid" with example.

    1. Sandipan,

      By default only CQ OOTB supported language is shown in translator language grid. You can modify /etc/languages/languages to show additional languages. Then you can use translator UI to add additional key value pair for new language. Hope it make sense.


  4. Hi Yogesh,

    Great article. Thanks for the valuable info and tips.

    However, I was wondering if you can have a further separation of the translation keys, e.g. /apps/myproject/i18n/author and /apps/myproject/i18n/publish, in order to store author-only and/or frontend-only translations.

    I noticed that this is possible to do in JSP scripts, where the keys are automatically resolved. However, the same doesn't go for JS script, where no translations are shown, since they are not resolved for some reason.

    Any ideas on this?

    1. Unfortunately this is not possible using resource bundle path. However I guess you can use java resource bundle api to load resource bundle according to your need and then translate it. For example creating new tag library similar to which can take config in to account.

      Also not sure why you will have different translation for author and publish.


  5. Great blog, Yogesh! This article, in particular, gave me several directions to look in for a problem I'm having. Thanks! And please keep it up :)

  6. Hi Yogesh,

    we cant see spanish US (es-US)locale in the language support. i can see other country specific spanish locales but United States is not listed.

    Is there a way to add this ?

    below code is also code setting the right locale in DAY CQ 5.4

    else if (currentPage.getPath().contains("/aplication/es")){



    1. Please check,

      You can get page locale from
      Locale pageLocale = currentPage.getLanguage(false);
      //If above bool is set to true. CQ looks in to page path rather than jcr:language property.

      Also es should be supported language. And with Java standard es_US should be supported.


  7. Is it possible to change the default language for authors from english to another language? If it is, how could it be done?

    1. Hello,

      Yes it is possible. To do that login as user with admin access or access to User dashboard. Then go to user preferences and then select language. check


  8. How to avoid call of http://localhost:4502/libs/cq/i18n/dict.lang-code.json and make it http://localhost:4502/apps/cq/i18n/dict.lang-code.json

  9. Thanks for the blog loaded with so many information. Stopping by your blog helped me to get what I was looking for. Chinese translation

  10. There are a number of plays of food show. This show is the greater podcast that can be watched at YouTube also. You would also like to listen about the Company where I do job which provides best creative writer India which can make your show more popular. source