xdocs/services/localization-service.xml - turbine-core - Git at Google

 <?xml version="1.0"?>

 <!--
  Licensed to the Apache Software Foundation (ASF) under one
  or more contributor license agreements.  See the NOTICE file
  distributed with this work for additional information
  regarding copyright ownership.  The ASF licenses this file
  to you under the Apache License, Version 2.0 (the
  "License"); you may not use this file except in compliance
  with the License.  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing,
  software distributed under the License is distributed on an
  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  KIND, either express or implied.  See the License for the
  specific language governing permissions and limitations
  under the License.
 -->

 <document>
  <properties>
   <title>Turbine Services - Localization Service</title>
   <author email="jvanzyl@apache.org">Jason van Zyl</author>
   <author email="seade@backstagetech.com.au">Scott Eade</author>
  </properties>

 <body>

 <section name="Localization Service">

 <p>
 There is a Turbine service that makes it easy to add localization support
 to your application.
 </p>

 </section>

 <section name="Configuration">

 <source><![CDATA[
 # -------------------------------------------------------------------
 #
 #  S E R V I C E S
 #
 # -------------------------------------------------------------------
 # Classes for Turbine Services should be defined here.
 # Format: services.[name].classname=[implementing class]
 #
 # To specify properties of a service use the following syntax:
 # service.[name].[property]=[value]

 services.LocalizationService.classname=org.apache.turbine.services.localization.TurbineLocalizationService
 .
 .
 .
 # -------------------------------------------------------------------
 #
 #  L O C A L I Z A T I O N  S E R V I C E
 #
 # -------------------------------------------------------------------

 # Default ResourceBundle and language/country codes used by the
 # TurbineLocalizationService.
 #
 locale.default.bundle=MyBundle
 locale.default.language=en
 locale.default.country=
 .
 .
 .
 ]]></source>

 </section>

 <section name="Resource Bundles">

 <p>
 Resource bundles are basically property files.  You might have one for the "en"
 locale thus:
 </p>

 <source><![CDATA[
 LABEL_ORGANIZATION = organisation
 CURRENT_RECORD = Record {0} of {1}
 ]]></source>

 <p>
 and another for the "en_US" locale thus:
 </p>

 <source><![CDATA[
 LABEL_ORGANIZATION = organization
 ]]></source>

 <p>
 Please see the <em>java.util.ListResourceBundle</em> and
 <em>java.util.ResourceBundle</em> classes for more information.
 </p>

 </section>

 <section name="Usage">

 <source><![CDATA[
 TurbineServices.getInstance().getService(LocalizationService.LOCALIZATION)
     .getString("LABEL_ORGANIZATION");
 ]]></source>

 <p>
 Wow. That is a lot of typing. That could be easily shortened to this:
 </p>

 <source><![CDATA[
 Localization.getString("LABEL_ORGANIZATION");
 ]]></source>

 <p>
 The hard example above was given as an example of using Services. The easy
 example is the one that you really should be using. Another cool feature
 of the Localization class is that you can pass in a HttpRequest object like
 this:
 </p>

 <source><![CDATA[
 Localization.getString("LABEL_ORGANIZATION", data.getRequest());
 ]]></source>

 <p>
 This has the added effect of using the Accept-Language HTTP header to determine
 which language to display based on what setting the user has defined in
 the browser. Can you say Dynamic Localization? ;-)
 </p>

 <p>
 The Localization class also supports the formatting of localized strings containing
 parameters, such as in
 </p>

 <source><![CDATA[
 Localization.format(Localization.getDefaultBundle(),
     Localization.getLocale(data.getRequest(),
     "CURRENT_RECORD",
     recno, all);
 ]]></source>

 <p>
 This actually doesn't look too nice, however the call using the LocalizationTool
 from a Velocity template (see below) just deflates to
 </p>

 <source><![CDATA[
 $l10n.format("CURRENT_RECORD", $recno, $all);
 ]]></source>

 </section>

 <section name="Usage from a template">

 <p>
 Turbine provides a <a href="../howto/pullmodel-howto.html">Pull tool</a> to make it
 very easy to access localized text from within your templates.  To configure
 this you need to add the following to your TurbineResouces.properties:
 </p>

 <source><![CDATA[
 tool.request.l10n = org.apache.turbine.services.localization.LocalizationTool
 ]]></source>

 <p>
 You can then use it in your templates thus:
 </p>

 <source><![CDATA[
 $l10n.LABEL_ORGANIZATION
 ]]></source>

 <p>
 A string with arguments can be used thus:
 </p>

 <source><![CDATA[
 // No arguments
 $l10n.LABEL_ORGANIZATION
 // One argument
 $l10n.format("STRING_KEY_ONE_ARG" "arg1")
 // Two arguments
 $l10n.format("CURRENT_RECORD" "1", "5")
 // Two arguments
 $l10n.format("STRING_KEY_3_OR_MORE_ARGS" ["arg1", "arg2", "arg3"])
 ]]></source>

 </section>

 </body>
 </document>
	<?xml version="1.0"?>

	<!--
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	-->

	<document>
	<properties>
	<title>Turbine Services - Localization Service</title>
	<author email="jvanzyl@apache.org">Jason van Zyl</author>
	<author email="seade@backstagetech.com.au">Scott Eade</author>
	</properties>

	<body>

	<section name="Localization Service">

	<p>
	There is a Turbine service that makes it easy to add localization support
	to your application.
	</p>

	</section>

	<section name="Configuration">

	<source><![CDATA[
	# -------------------------------------------------------------------
	#
	# S E R V I C E S
	#
	# -------------------------------------------------------------------
	# Classes for Turbine Services should be defined here.
	# Format: services.[name].classname=[implementing class]
	#
	# To specify properties of a service use the following syntax:
	# service.[name].[property]=[value]

	services.LocalizationService.classname=org.apache.turbine.services.localization.TurbineLocalizationService
	.
	.
	.
	# -------------------------------------------------------------------
	#
	# L O C A L I Z A T I O N S E R V I C E
	#
	# -------------------------------------------------------------------

	# Default ResourceBundle and language/country codes used by the
	# TurbineLocalizationService.
	#
	locale.default.bundle=MyBundle
	locale.default.language=en
	locale.default.country=
	.
	.
	.
	]]></source>

	</section>

	<section name="Resource Bundles">

	<p>
	Resource bundles are basically property files. You might have one for the "en"
	locale thus:
	</p>

	<source><![CDATA[
	LABEL_ORGANIZATION = organisation
	CURRENT_RECORD = Record {0} of {1}
	]]></source>

	<p>
	and another for the "en_US" locale thus:
	</p>

	<source><![CDATA[
	LABEL_ORGANIZATION = organization
	]]></source>

	<p>
	Please see the <em>java.util.ListResourceBundle</em> and
	<em>java.util.ResourceBundle</em> classes for more information.
	</p>

	</section>

	<section name="Usage">

	<source><![CDATA[
	TurbineServices.getInstance().getService(LocalizationService.LOCALIZATION)
	.getString("LABEL_ORGANIZATION");
	]]></source>

	<p>
	Wow. That is a lot of typing. That could be easily shortened to this:
	</p>

	<source><![CDATA[
	Localization.getString("LABEL_ORGANIZATION");
	]]></source>

	<p>
	The hard example above was given as an example of using Services. The easy
	example is the one that you really should be using. Another cool feature
	of the Localization class is that you can pass in a HttpRequest object like
	this:
	</p>

	<source><![CDATA[
	Localization.getString("LABEL_ORGANIZATION", data.getRequest());
	]]></source>

	<p>
	This has the added effect of using the Accept-Language HTTP header to determine
	which language to display based on what setting the user has defined in
	the browser. Can you say Dynamic Localization? ;-)
	</p>

	<p>
	The Localization class also supports the formatting of localized strings containing
	parameters, such as in
	</p>

	<source><![CDATA[
	Localization.format(Localization.getDefaultBundle(),
	Localization.getLocale(data.getRequest(),
	"CURRENT_RECORD",
	recno, all);
	]]></source>

	<p>
	This actually doesn't look too nice, however the call using the LocalizationTool
	from a Velocity template (see below) just deflates to
	</p>

	<source><![CDATA[
	$l10n.format("CURRENT_RECORD", $recno, $all);
	]]></source>

	</section>

	<section name="Usage from a template">

	<p>
	Turbine provides a <a href="../howto/pullmodel-howto.html">Pull tool</a> to make it
	very easy to access localized text from within your templates. To configure
	this you need to add the following to your TurbineResouces.properties:
	</p>

	<source><![CDATA[
	tool.request.l10n = org.apache.turbine.services.localization.LocalizationTool
	]]></source>

	<p>
	You can then use it in your templates thus:
	</p>

	<source><![CDATA[
	$l10n.LABEL_ORGANIZATION
	]]></source>

	<p>
	A string with arguments can be used thus:
	</p>

	<source><![CDATA[
	// No arguments
	$l10n.LABEL_ORGANIZATION
	// One argument
	$l10n.format("STRING_KEY_ONE_ARG" "arg1")
	// Two arguments
	$l10n.format("CURRENT_RECORD" "1", "5")
	// Two arguments
	$l10n.format("STRING_KEY_3_OR_MORE_ARGS" ["arg1", "arg2", "arg3"])
	]]></source>

	</section>

	</body>
	</document>