Customizing Alfresco Share i18n Properties

cancel
Showing results for 
Search instead for 
Did you mean: 

Customizing Alfresco Share i18n Properties

Intermediate II
0 14 3,610

Introduction

In previous blog posts I have described how to customize Alfresco Share through the use of Component extensions. This is only one of the new extensibility features that are currently available in the Alfresco Community source (and will be included in Alfresco Enterprise 4.0). In this post I'll start describing the changes we've made to Spring Surf in order to further simplify customization use cases starting with demonstrating how to customize Web Script i18n properties.

Tutorial

This tutorial describes how to override the default i18n properties for the User Dashboard title bar. It will show how to use the SurfBug and the Web Scripts UI to find the Web Scripts that need to be targeted and then demonstrate how to create the necessary extension module configuration and files to achieve the customization.

1. Logon to Alfresco Share and navigate to the user dashboard.

2. Open a new browser window or tab and enable SurfBug (http://localhost:8080/share/page/surfBugStatus - if you're using default port settings on your local machine)

3. Refresh the dashboard page and click on the title to see the information about the Component/Sub-Component that is rendering it

4. Make a note of the 'url' value in the Component details (which should be '/components/title/user-dashboard-title')

Screen shot showing Alfresco Share user dashboard with Surf Bug pop up

5. Open a new browser window or tab at the Web Scripts Home page (http://localhost:8080/share/service/index) and click on 'Browse by Web Script URI'

6. Find and click on '/components/title/user-dashboard-title' to see the information about the Web Script that is rendering the title bar.

Screen shot showing how to search for a Web Script by URI

7. Click on the link next to 'Id' to see all the information about the Web Script.

Screen shot showing Title Web Script basic information

8. The key piece of information that we're looking for here is the package that the Web Script belongs in which is 'org.alfresco.components.title' because we're aiming to customize the code defined in that package.

Screen shot showing detailed information on the Title Web Script

9. Edit your 'blog-demo.xml' (created in the previous blog post tutorials) and add the following module definition:

<module>
    <id>Blog Module (i18n property change)</id>
    <customizations>
        <customization>
            <targetPackageRoot>org.alfresco.components.title</targetPackageRoot>
            <sourcePackageRoot>blog.demo.customization</sourcePackageRoot>
        </customization>
   </customizations>
</module>

10. On the page showing the information about the Web Script scroll down to find the section on the i18n properties file which will show both the fully qualified name of the file along with its contents.

Screen shot showing detailed information about the Title Web Script

Create a new file called 'user-dashboard-title.get_en.properties' and place it in package 'webscripts.blog.demo.customization' package that we defined as the 'sourcePackageRoot' element in the module configuration. The file should contain the following:

header.dashboard=Customized Title Bar!

There's a couple of important things to note here!

1. The file name is NOT exactly the same... although a Web Script  will broaden the locale of it's search (i.e. from 'en_GB' to 'en' to  the default properties file - extensions will NOT)

2. The source package has been prefixed with 'webscripts.' - this is a requirement of the class loader used to find Web Script files.

11. Re-build the JAR, copy it to 'webapps/share/WEB-INF/lib' (or the equivalent directory for your web server), restart the web server and deploy the new module (hopefully you should be used to this process by now - if not, see the earlier blog posts for more details).

Logon to Alfresco Share you should now see that the title bar now says 'Customized Title Bar!'https://community.alfresco.com/api/core/v3/attachments/12032/data

Screen shot showing the customized title bar

Background Information

When you create a 'customization' you are creating a mapping from a package to you want to update to a package that you are providing. When any file is processed in that package all mapped extension module packages are searched for a matching file name. Typically a Web Script might be represented by a JavaScript controller, an i18n properties file and a FreeMarker template. They must all be defined in the same package with a similar file name prefix as the Web Script descriptor file to which they are related. This package mapping allows us to target multiple files in a single customization rather than specifying every file individually. It also allows us to broaden our target. For example we could have targeted 'org.alfresco' - but it is important to note that the remainder of the package will be applied to the source (so the extensibility framework would be looking for a matching file in the 'blog.demo.customization.components.title' package).

When you provide an i18n properties file extension the properties in the extension file are merged into the 'base' file (any duplicates are replaced with those from the extension file). If multiple modules extend the same properties file then the last module in the deployment list will 'win'.

It is not necessary to provide an extension file for every base in the Web Script - only those that you wish to extend. For example - if a Web Script has controller, properties and template files you don't need to provide extensions to all 3 if you just wish to override some i18n properties.

It's also possible to provide an extension file to a Web Script that does not have that base file. For example, it is entirely possible to extend a Web Script with a JavaScript controller or i18n properties file even if those files are not in the base.

In the next post I'll demonstrate how to extend a Web Script JavaScript controller.

14 Comments
Active Member
Thank you, David. It's very useful, I've just translated Alfresco Share 4.0a то Russian.
Active Member
This seems to be a great way of modularizing the Share language packs which currently are shipped with Alfresco. Some of our customers have expressed the desire to deactivate certain languages in order to simplify I18n management of their own custom components and pages. Providing a language module with a global evaluator would go a long way in having a plug-and-(activate-and-)play style of I18n. Are there any plans of Alfresco to go into that direction?

Thanks for a greate blog series David.
Intermediate II
Thanks for the feedback -  it's much appreciated!

The intended purpose was not so much for manipulating languages as a whole, but rather to allow the content of the message strings to be customized.  I don't believe it will be possible to modify all the i18n strings in Share using this technique because it only allows for customization of WebScript specific i18n properties and I believe that they are other properties files (such as 'common.properties') which are not part of a WebScript and cannot be customized this way.
Active Member
To override msg keys in slingshot.properties OR common.properties start by creating a new spring mvc xontext file that will make sure an additional .properties file is loaded that will override shares msg keys:

/alfresco/web-extension/custom-slingshot-acme-context.xml
alfresco.messages.acme

2. Then create the actual .properties who's keys will override the ones in slingshot.properties:

/alfresco/messages/acme.properties
## Rename Roles
role.SiteManager=Acme Manager
role.SiteCollaborator=Acme Collaborator
role.SiteContributor=Acme Contributor
role.SiteConsumer=Acme Consumer


This works in Alfresco 4 AND in Alfresco 3
Active Member
...ehrmm, the [code] shall obviously not be there.... :-= (was pasted form a wiki editor)
Intermediate II
Fixed the [code] for you Smiley Happy
Active Member
Hello David.

I tried to customize Web Script i18n and encountered strange extension behavior. I'm using Alfresco 4.0.d and I tried to support - English and Russian. The issue arises if the browser sends 'short' locales ('en', 'ru', etc) instead of 'long' ones ('en-US', 'ru-RU', etc).


Test case #1:
- I have only *_en.properties and *_ru.properties in extension, Share server is started with en_US.UTF-8 locale.

Test case #1 results:
- en-US browser locale - custom en message
- ru-RU browser locale - custom ru message
- en browser locale - default message                     - smth bad here
- ru browser locale - custom _en_ message           - smth bad here


Test case #2:
- I have only *_en.properties and *_ru.properties in extension, Share server is started with ru_RU.UTF-8 locale.

Test case #2 results:
- en-US browser locale - custom en message
- ru-RU browser locale - custom ru message
- en browser locale - custom _ru_ message            - smth bad here
- ru browser locale - default message                      - smth bad here


Test case #3:
- I have *_en.properties, *_ru.properties plus *.properties in extension, Share server is started with en_US.UTF-8 locale.

Test case #3 results:
- en-US browser locale - custom en message
- ru-RU browser locale - custom ru message
- en browser locale - custom en message
- ru browser locale - custom _en_ message          - smth bad here


Test case #4:
- I have *_en.properties, *_ru.properties plus *.properties in extension, Share server is started with en_US.UTF-8 locale.

Test case #4 results:
- en-US browser locale - custom en message
- ru-RU browser locale - custom ru message
- en browser locale - custom _ru_ message          - smth bad here
- ru browser locale - custom _en_ message          - smth bad here
Intermediate II
Hi Alexey,

Thanks for finding this problem - could I ask that you raise it at https://issues.alfresco.com please?  I've checked the Surf libs that are in Alfresco Community 4.0d and it is missing a couple of i18n extension handling changes but none that I think might be causing this problem.

Regards,
Dave
Active Member
Active Member
[...] you can perform the same types of customization described in my earlier blogs for extending i18n properties files, JavaScript controllers and the FreeMarker templates of a [...]
Active Member
Hi I've customized both existing _en.properties file and added a new _ja.properties one.

When I display the site in japanese:
I can see that the customized webscript use the _en file instead of the japanese one. All the rest of the site display correctly in Japanese, but everything I've customized display in english. Is this a known bug or have I forgotten something?
Intermediate II
This could be a bug in Surf... could you raise an Alfresco issue for this please at http://issues.alfresco.com.

The only suggestion I can think of (off the top of my head) that might work is that you try providing a more specific locale file (e.g. ja_JP) for the extension file. Surf should be processing extensions for message keys based on the specificity of the available locale files.
Active Member
yes just realize it's the same bug as Alexey. Thanks
Active Member
[...] you can perform the same types of customization described in my earlier blogs for extending i18n properties files, JavaScript controllers and the FreeMarker templates of a [...]