Author: thomas.heute(a)jboss.com Date: 2009-12-09 03:43:21 -0500 (Wed, 09 Dec 2009) New Revision: 976 Modified: portal/trunk/docs/reference-guide/en/modules/development/Internationalization_Configuration.xml Log: More cleanup/fix Modified: portal/trunk/docs/reference-guide/en/modules/development/Internationalization_Configuration.xml =================================================================== --- portal/trunk/docs/reference-guide/en/modules/development/Internationalization_Configuration.xml 2009-12-09 03:23:12 UTC (rev 975) +++ portal/trunk/docs/reference-guide/en/modules/development/Internationalization_Configuration.xml 2009-12-09 08:43:21 UTC (rev 976) @@ -8,8 +8,6 @@ <para> All aspects of internationalization in GateIn products are covered. You should have a general knowledge of Internationalization in Java products. Sun created a <ulink url="http://java.sun.com/docs/books/tutorial/i18n/TOC.html">... internationalization tutorial</ulink> . </para> - <section id="sect-Reference_Guide-Overview-Introduction"> - <title>Introduction</title> <para>All embedded applications contains property files for various languages. They are packaged with the portlets applications in a WEB-INF/classes/locale/ directory.</para> <para> You should notice that @@ -85,7 +83,7 @@ <area id="i18n.locales.configuration.description" coords='7' /> <area id="i18n.locales.configuration.orientation" coords='22' /> </areaspec> -<programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?> <locales-config> <locale-config> <locale>en</locale> @@ -144,77 +142,114 @@ </callout> </calloutlist> </programlistingco> - + </section> + <section> + <title>ResourceBundleService</title> <para> - 1 ResourceBundleService + The resource bundle service is configured in: <filename>02portal.war:/WEB-INF/conf/common/common-configuration.xml</filename>: </para> - <para> - The resource bundle service is configured here: // <ulink url="http://fisheye.exoplatform.org/browse/projects/portal/trunk/web... - </para> - <para> - Caution: Other GateIn products like DMS use dedicated configuration file called "resource-bundle-configuration.xml". - </para> - <para> - A typical configuration looks like this one: {code:xml} &lt;component&gt; &lt;key&gt;org.exoplatform.services.resources.ResourceBundleService&lt;/key&gt; &lt;type&gt;org.exoplatform.services.resources.jcr.ResourceBundleServiceImpl&lt;/type&gt; &lt;init-params&gt; - </para> - <para> - &lt;values-param&gt; &lt;name&gt;classpath.resources&lt;/name&gt; &lt;description&gt;The resources that start with the following package name should be loaded from file system&lt;/description&gt; &lt;value&gt;locale.portlet&lt;/value&gt; &lt;/values-param&gt; - </para> - <para> - &lt;values-param&gt; &lt;name&gt;init.resources&lt;/name&gt; &lt;description&gt;Store the following resources in the DB for the first launch &lt;/description&gt; &lt;value&gt;locale.portal.expression&lt;/value&gt; &lt;value&gt;locale.portal.services&lt;/value&gt; &lt;value&gt;locale.portal.webui&lt;/value&gt; &lt;value&gt;locale.portal.custom&lt;/value&gt; - </para> - <para> - &lt;value&gt;locale.navigation.portal.classic&lt;/value&gt; &lt;value&gt;locale.navigation.group.platform.administrators&lt;/value&gt; &lt;value&gt;locale.navigation.group.platform.users&lt;/value&gt; &lt;value&gt;locale.navigation.group.platform.guests&lt;/value&gt; &lt;value&gt;locale.navigation.group.organization.management.executive-board&lt;/value&gt; &lt;/values-param&gt; - </para> - <para> - &lt;values-param&gt; &lt;name&gt;portal.resource.names&lt;/name&gt; &lt;description&gt;The properties files of the portal, these files will be merged into one ResoruceBundle properties &lt;/description&gt; &lt;value&gt;locale.portal.expression&lt;/value&gt; &lt;value&gt;locale.portal.services&lt;/value&gt; &lt;value&gt;locale.portal.webui&lt;/value&gt; &lt;value&gt;locale.portal.custom&lt;/value&gt; &lt;/values-param&gt; - </para> - <para> - &lt;/init-params&gt; &lt;/component&gt; - </para> - -<programlisting> -There are three parameters: *classpath.resources*, *init.resources*, and *portal.resource.names*. We will talk later about _classpath.resources_. -In _init.resources_ you have to define _*all resources*_ that you want use in the product, independently of the fact that they belong to the portal or to the navigation. All these resources are stored in JCR at the first launch of your product. After that, you only can modify these resources using the [Portal:Internationalization Portlet]. -h2. Portal Resource Bundle -The parameter *portal.resource.names* defines all resources that belong to the *Portal Resource Bundle*. This means that these resources are merged to a *single resource bundle* which is accessible from anywhere in GateIn products. As mentioned, all these keys are located in the same bundle, which is separated from the navigation resource bundles. -h2. Navigation Resource Bundles -There is a resource bundle for each navigation. A navigation can exist for user, groups, and portal. In the example above you see bundle definitions for the navigation of the classic portal and of four different groups. Each of these resource bundles lives in a different sphere, they are independent of each other and they do not belong to the portal.resource.names parameter (because they are not mentioned in _portal.resource.names_). -As you learned in the introduction you must put the properties for a group in the _WEB-INF/classes/locale/navigation/group/_ folder. -Example: -*.../portal/trunk/web/portal/src/main/webapp/WEB-INF/classes/locale/navigation/group/organization/management/executive-board_en.properties* -The folder and file names must correspond to the group hierarchy. The group name "executive-board" is followed by the iso 639 code. For each language you defined in the LocalesConfig you must provide a resource file. -If you ever change the name of a group you also need to change the name of the folder and/or files of the correspondent navigation resource bundles. -You already know the content of _executive-board_en.properties_: -{code:none} -organization.title=Organization + <programlistingco> + <areaspec> + <area id="i18n.rb.service.classpath_resources" coords='6' /> + <area id="i18n.rb.service.init_resources" coords='11' /> + <area id="i18n.rb.service.portal_resource_names" coords='24' /> + </areaspec> + <programlisting><![CDATA[<component> + <key>org.exoplatform.services.resources.ResourceBundleService</key> + <type>org.exoplatform.services.resources.impl.SimpleResourceBundleService</type> + <init-params> + <values-param> + <name>classpath.resources</name> + <description>The resources that start with the following package name should be load from file system</description> + <value>locale.portlet</value> + </values-param> + <values-param> + <name>init.resources</name> + <description>Initiate the following resources during the first launch</description> + <value>locale.portal.expression</value> + <value>locale.portal.services</value> + <value>locale.portal.webui</value> + <value>locale.portal.custom</value> + <value>locale.navigation.portal.classic</value> + <value>locale.navigation.group.platform.administrators</value> + <value>locale.navigation.group.platform.users</value> + <value>locale.navigation.group.platform.guests</value> + <value>locale.navigation.group.organization.management.executive-board</value> + </values-param> + <values-param> + <name>portal.resource.names</name> + <description>The properties files of the portal , those file will be merged + into one ResoruceBundle properties </description> + <value>locale.portal.expression</value> + <value>locale.portal.services</value> + <value>locale.portal.webui</value> + <value>locale.portal.custom</value> + </values-param> + </init-params> +</component>]]></programlisting> + <calloutlist> + <callout arearefs="i18n.rb.service.classpath_resources"> + <para> + <emphasis>classpath.resources</emphasis> + We will talk later about classpath.resources + </para> + </callout> + <callout arearefs="i18n.rb.service.init_resources"> + <para> + <emphasis>init.resources</emphasis> + TODO + </para> + </callout> + <callout arearefs="i18n.rb.service.portal_resource_names"> + <para> + <emphasis>portal.resource.names</emphasis> + Defines all resources that belong to the <emphasis>Portal Resource Bundle</emphasis>. + This means that these resources are merged to a single resource bundle which is accessible from anywhere in GateIn products. + As mentioned, all these keys are located in the same bundle, which is separated from the navigation resource bundles. + </para> + </callout> + </calloutlist> + </programlistingco> + </section> + <section> + <title>Navigation Resource Bundles</title> + <para> + There is a resource bundle for each navigation. A navigation can exist for user, groups, and portal. In the example above you see + bundle definitions for the navigation of the classic portal and of four different groups. Each of these resource bundles lives in + a different sphere, they are independent of each other and they do not belong to the portal.resource.names parameter (because they + are not mentioned in portal.resource.names). + </para> + <para> + As you learned in the introduction you must put the properties for a group in the WEB-INF/classes/locale/navigation/group/ folder. + Such as: <literal>/WEB-INF/classes/locale/navigation/group/organization/management/executive-board_en.properties</literal> + The folder and file names must correspond to the group hierarchy. The group name "executive-board" is followed by the iso 639 code. + For each language you defined in the LocalesConfig you must provide a resource file. + If you ever change the name of a group you also need to change the name of the folder and/or files of the correspondent navigation + resource bundles. + Content of executive-board_en.properties: + <programlisting>organization.title=Organization organization.newstaff=New Staff -organization.management=Management -</programlisting> +organization.management=Management</programlisting> + </para> <para> - This resource bundle is only accessible for the navigation of the ~~organization.management.executive-board~~ group. + This resource bundle is only accessible for the navigation of the organization.management.executive-board group. </para> + </section> + <section> + <title> + Portlets + </title> <para> - 1 Portlet + classpath.resources </para> <para> - 1.1 classpath.resources + Portlets are independent application and they deliver their own resource files. </para> <para> - Portlets are independent application and they deliver their own resource files. You can find an example for the GadgetPortlet: <!-- LB --> .../WEB-INF/classes/locale/portlet/gadget/GadgetPortlet/en.properties <ulink url="http://fisheye.exoplatform.org/browse/projects/portal/trunk/por... /> + All shipped-in portlet resources are located in the <emphasis role="bold">locale/portlet</emphasis> subfolder. + The ResourceBundleService parameter <emphasis role="bold">classpath.resources</emphasis> defines this subfolder. + <!-- Doing so the resource file that are in ~~locale/portlet~~ will never be stored in the JCR and reloaded at each start of the application server. --> </para> - <para> - All portlet resources are located in the <emphasis role="bold">locale/portlet</emphasis> subfolder. The ResourceBundleService parameter <emphasis role="bold">classpath.resources</emphasis> defines exactly this subfolder. Doing so the resource file that are in ~~locale/portlet~~ will never be stored in the JCR and reloaded at each start of the application server. - </para> - -<programlisting>&lt;values-param&gt; - &lt;name&gt;classpath.resources&lt;/name&gt; - &lt;description&gt;The resources that start with the following package name should - be loaded from file system&lt;/description&gt; - &lt;value&gt;locale.portlet&lt;/value&gt; -&lt;/values-param&gt; -</programlisting> - </section> <section id="sect-Reference_Guide-Overview-Example"> <title>Example</title> @@ -222,18 +257,23 @@ Let's suppose you want to add a Spanish translation to the GadgetPortlet. </para> <para> - Create the file in: <filename>.../WEB-INF/classes/locale/portlet/gadget/GadgetPortlet</filename> + Create the file <literal>GadgetPortlet_es.properties</literal> in: <filename>WEB-INF/classes/locale/portlet/gadget/GadgetPortlet</filename> </para> <para> - In <emphasis role="bold">portlet.xml</emphasis>, add Spanish as a <emphasis role="bold">supported-locale</emphasis>, the <emphasis role="bold">resource-bundle</emphasis> is already declared and is the same for all languages : {code:xml} &lt;supported-locale&gt;en&lt;/supported-locale&gt; &lt;supported-locale&gt;es&lt;/supported-locale&gt; &lt;resource-bundle&gt;locale.portlet.gadget.GadgetPortlet&lt;/resource-bundle&gt; {code} - </para> + In <emphasis role="bold">portlet.xml</emphasis>, add Spanish as a <emphasis role="bold">supported-locale</emphasis> ('es' is the 2 letters code for Spanish), the <emphasis role="bold">resource-bundle</emphasis> is already declared and is the same for all languages : + </para> + <programlisting role="XML"><![CDATA[<supported-locale>en</supported-locale> +<supported-locale>es</supported-locale> +<resource-bundle>locale.portlet.gadget.GadgetPortlet</resource-bundle>]]></programlisting> <para> - Find <ulink type="http" url="http://developers.sun.com-portalserver-reference-techart-i18n-portlets.html" /> for more details about portlet internationalization. + See the portlet specification for more details about portlet internationalization. </para> + <section> + <title>Standard portlet resource keys</title> + </section> <para> - 1.1 Standard Portlet Resource Keys There are three standard keys defined : Title, Short Title and Keywords. Keywords contain a comma-separated list of keywords. + The portlet specifications defines three standard keys: Title, Short Title and Keywords. Keywords contain a comma-separated list of keywords. </para> - <programlisting> javax.portlet.title=Breadcrumbs Portlet javax.portlet.short-title=Breadcrumbs javax.portlet.keywords=Breadcrumbs, Breadcrumb @@ -243,25 +283,26 @@ <section id="sect-Reference_Guide-Overview-Access"> <title>Access</title> <para> - Whenever you want to display a property in the user language you use its <emphasis>key</emphasis>. Using the below access method the translation is returned in the preferred language of the current http session: + Whenever you want to display a property in the user language you use its <emphasis>key</emphasis>. Using the below access method the translation is returned in the preferred language for the connected user: </para> <itemizedlist> <listitem> <para> - Groovy Template{code}{code} + Groovy Template + <programlisting>TODO</programlisting> </para> </listitem> <listitem> <para> Java +<programlisting>WebuiRequestContext context = WebuiRequestContext.getCurrentInstance() ; +ResourceBundle res = context.getApplicationResourceBundle() ; +String translatedString = res.getString(key); +</programlisting> </para> </listitem> </itemizedlist> -<programlisting>WebuiRequestContext context = WebuiRequestContext.getCurrentInstance() ; -ResourceBundle res = context.getApplicationResourceBundle() ; -String translatedString = res.getString(key); -</programlisting> </section> <section id="sect-Reference_Guide-Overview-Debugging_resource_bundle_usage"> @@ -273,9 +314,7 @@ This feature translates a key to the same key value. For instance, the translated value for the key "organization.title" is simply the value "organization.title". Selecting that language allows to use the portal and its applications with <emphasis role="bold">all the keys visible</emphasis> and it is easy to find out the correct key for a given label in the portal page. </para> </section> - - </section> - + </section> </section>