<?xml version="1.0" encoding="UTF-8"?>
<!--
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 id="stock-tracker.localization">
    <properties>
        <title>Localization</title>
    </properties>

    <body>
        <p>
            In Java, any translatable text is generally stored in a set of localized property files
            called "resource bundles". The appropriate file is loaded at runtime for either the
            default locale or an explicitly selected non-default locale. While it is possible to
            use standard Java resource bundles in a Pivot application, Pivot adds support for
            JSON-based resource bundles that are slightly more flexible the built-in
            properties-based bundles. JSON resource bundles allow developers to more easily work
            with UTF-8 encoded resource strings, and also natively support hierarchical data, which
            can only be simulated when using properties files.
        </p>

        <p>
            Stock Tracker provides two resource files, one for English users and one for
            French-speaking users:
        </p>

        <source type="jscript">
            <![CDATA[
            {   stockTracker: "Pivot Stock Tracker",
                symbol: "Symbol",
                companyName: "Company",
                value: "Value",
                openingValue: "Open",
                highValue: "High",
                lowValue: "Low",
                change: "Change",
                volume: "Volume",
                addSymbol: "Add symbol",
                removeSymbol: "Remove selected symbols",
                lastUpdate: "Last Update",
                dataProvidedBy: "Data provided by",
                yahooFinance: "Yahoo! Finance"
            }
            ]]>
        </source>
        <p class="caption">StockTracker.json</p>

        <source type="jscript">
            <![CDATA[
            {   stockTracker: "La Bourse Pivot",
                symbol: "Code",
                companyName: "Société",
                value: "Cours",
                openingValue: "Ouverture",
                highValue: "+ Haut",
                lowValue: "+ Bas",
                change: "Variation",
                volume: "Volume",
                addSymbol: "Ajouter un code",
                removeSymbol: "Enlever codes sélectionnés",
                lastUpdate: "Dernier échange",
                dataProvidedBy: "Données fournies par",
                yahooFinance: "Yahoo! Finance"
            }
            ]]>
        </source>
        <p class="caption">StockTracker_fr.json</p>

        <p>
            As noted in earlier sections, references to these string resources can be embedded
            directly within a BXML file:
        </p>

        <source type="xml">
            <![CDATA[
            <Form styles="{padding:0, fill:true, showFlagIcons:false, showFlagHighlight:false,
                leftAlignLabels:true}">
                <Form.Section>
                    <bxml:define>
                        <stocktracker:ValueMapping bxml:id="valueMapping"/>
                        <stocktracker:ChangeMapping bxml:id="changeMapping"/>
                        <stocktracker:VolumeMapping bxml:id="volumeMapping"/>
                    </bxml:define>

                    <Label bxml:id="valueLabel" Form.label="%value"
                        textKey="value" textBindMapping="$valueMapping"
                        styles="{horizontalAlignment:'right'}"/>
                    <Label bxml:id="changeLabel" Form.label="%change"
                        textKey="change" textBindMapping="$changeMapping"
                        styles="{horizontalAlignment:'right'}"/>
                    <Label bxml:id="openingValueLabel" Form.label="%openingValue"
                        textKey="openingValue" textBindMapping="$valueMapping"
                        styles="{horizontalAlignment:'right'}"/>
                    <Label bxml:id="highValueLabel" Form.label="%highValue"
                        textKey="highValue" textBindMapping="$valueMapping"
                        styles="{horizontalAlignment:'right'}"/>
                    <Label bxml:id="lowValueLabel" Form.label="%lowValue"
                        textKey="lowValue" textBindMapping="$valueMapping"
                        styles="{horizontalAlignment:'right'}"/>
                    <Label bxml:id="volumeLabel" Form.label="%volume"
                        textKey="volume" textBindMapping="$volumeMapping"
                        styles="{horizontalAlignment:'right'}"/>
                </Form.Section>
            </Form>
            ]]>
        </source>

        <p>
            The application loads the resources for the appropriate locale at startup, and the BXML
            serializer handles the details of resource substitution so the developer doesn't have
            to worry about it. The following applet demonstrates the Stock Tracker application run
            using the "fr" locale. No code changes are required; the same JAR files are used to
            execute both the English and French versions:
        </p>

        <application class="org.apache.pivot.tutorials.stocktracker.StockTracker"
            width="480" height="360">
            <libraries signed="true">
                <library>core</library>
                <library>web</library>
                <library>wtk</library>
                <library>wtk-terra</library>
                <library>tutorials</library>
            </libraries>
            <system-properties>
                <user.language>fr</user.language>
            </system-properties>
        </application>

        <p>
            Not all localization requirements can be handled by BXML alone, however. For example,
            Stock Tracker needs to manually handle the localization of the "last updated" message:
        </p>

        <source type="java">
            <![CDATA[
            DateFormat dateFormat = DateFormat.getDateTimeInstance(DateFormat.LONG,
                DateFormat.MEDIUM, Locale.getDefault());
            lastUpdateLabel.setText(dateFormat.format(new Date()));
            ]]>
        </source>

        <p>
            However, most static localization can be addressed in the BXML source itself, making it
            very easy to build internationalized applications in Pivot.
        </p>

        <h3>Summary</h3>

        <p>
            The examples in this section demonstrate the implementation of a simple but complete
            application implemented in Pivot. They discuss features common to many "real-world"
            applications, including UI markup, event handling, server communication, data binding,
            and internationalization, and should provide a good starting point for any developer
            interested in working with Pivot.
        </p>
    </body>
</document>
