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 

Solution:

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 com.day.cq.wcm.core.impl.LanguageManagerImpl: set langmgr.list.path = /apps/wcm/core/resources/languages at 
http://localhost:4502/system/console/configMgr/com.day.cq.wcm.core.impl.LanguageManagerImpl.

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. 


16 comments:

  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?

    ReplyDelete
    Replies
    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.

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

      Delete
  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

    ReplyDelete
    Replies
    1. Thanks a lot Linda for sharing this.

      Delete
    2. Is there any official documentation on this error?

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

      Yogesh

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

    ReplyDelete
    Replies
    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.

      Yogesh

      Delete
  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?

    ReplyDelete
    Replies
    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.

      http://www.wemblog.com/2011/12/how-to-use-multi-language-translation.html

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

      Yogesh

      Delete
  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 :)

    ReplyDelete
  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")){
    %>

    <%

    Thanks

    ReplyDelete
    Replies
    1. Please check,
      [1] http://www.wemblog.com/2011/12/how-to-use-multi-language-translation.html

      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.

      Yogesh

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

    ReplyDelete
    Replies
    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 http://dev.day.com/docs/en/cq/current/administering/security.html#Setting%20User%20and%20Group%20Preferences

      Yogesh

      Delete