<?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="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>
            The following application provides a simple demonstration of localization in Pivot:
        </p>

        <application class="org.apache.pivot.tutorials.localization.Localization"
            width="320" height="240">
            <libraries>
                <library>core</library>
                <library>wtk</library>
                <library>wtk-terra</library>
                <library>tutorials</library>
            </libraries>
        </application>

        <p>
            The following resource bundles are provided; if your default system locale is among
            these, you should see a localized version of the application. Otherwise, the default
            locale ("en") will be used:
        </p>

        <ul>
            <li>Localization.json</li>
            <li>Localization_cn.json</li>
            <li>Localization_de.json</li>
            <li>Localization_it.json</li>
            <li>Localization_ph.json</li>
        </ul>

        <p>
            The resource bundle for the default locale is shown below:
        </p>

        <source type="jscript">
            <![CDATA[
            {   firstName: "First name",
                lastName: "Last name",
                street: "Street",
                city: "City",
                state: "State",
                postalCode: "Zip",
                country: "Country"
            }
            ]]>
        </source>

        <p>
            The BXML source for the application is as follows. Note the use of the "%" prefix in
            the form label attributes. This prefix is known as the "resource resolution operator"
            in BXML. As the BXML is read, attribute values that begin with the "%" character are
            replaced by the corresponding values defined in the resource bundle:
        </p>

        <source type="xml" location="org/apache/pivot/tutorials/localization/localization.bxml">
            <![CDATA[
            <Window title="Localization" maximized="true"
                xmlns:bxml="http://pivot.apache.org/bxml"
                xmlns="org.apache.pivot.wtk">
                <windowStateListeners>
                    function windowOpened(window) {
                        window.requestFocus();
                    }
                </windowStateListeners>

                <Border styles="{padding:6}">
                    <Form>
                        <Form.Section>
                            <TextInput Form.label="%firstName"/>
                            <TextInput Form.label="%lastName"/>
                            <TextInput Form.label="%street"/>
                            <TextInput Form.label="%city"/>
                            <TextInput Form.label="%state" textSize="4"/>
                            <TextInput Form.label="%postalCode"/>
                            <TextInput Form.label="%country"/>
                        </Form.Section>
                    </Form>
                </Border>
            </Window>
            ]]>
        </source>

        <p>
            The Java source for the application is shown below:
        </p>

        <source type="java" location="org/apache/pivot/tutorials/localization/Localization.java">
            <![CDATA[
            package org.apache.pivot.tutorials.localization;

            import java.awt.Font;
            import java.awt.GraphicsEnvironment;
            import java.util.Locale;

            import org.apache.pivot.beans.BXMLSerializer;
            import org.apache.pivot.collections.Map;
            import org.apache.pivot.util.Resources;
            import org.apache.pivot.wtk.Application;
            import org.apache.pivot.wtk.DesktopApplicationContext;
            import org.apache.pivot.wtk.Display;
            import org.apache.pivot.wtk.Theme;
            import org.apache.pivot.wtk.Window;

            public class Localization implements Application {
                private Window window = null;

                public static final String LANGUAGE_KEY = "language";

                @Override
                public void startup(Display display, Map<String, String> properties) throws Exception {
                    String language = properties.get(LANGUAGE_KEY);
                    Locale locale = (language == null) ? Locale.getDefault() : new Locale(language);
                    Resources resources = new Resources(getClass().getName(), locale);

                    Theme theme = Theme.getTheme();
                    Font font = theme.getFont();

                    // Search for a font that can support the sample string
                    String sampleResource = (String)resources.get("firstName");
                    if (font.canDisplayUpTo(sampleResource) != -1) {
                        Font[] fonts = GraphicsEnvironment.getLocalGraphicsEnvironment().getAllFonts();

                        for (int i = 0; i < fonts.length; i++) {
                            if (fonts[i].canDisplayUpTo(sampleResource) == -1) {
                                theme.setFont(fonts[i].deriveFont(Font.PLAIN, 12));
                                break;
                            }
                        }
                    }

                    BXMLSerializer bxmlSerializer = new BXMLSerializer();
                    window = (Window)bxmlSerializer.readObject(Localization.class.getResource("localization.bxml"), resources);
                    window.open(display);
                }

                @Override
                public boolean shutdown(boolean optional) {
                    if (window != null) {
                        window.close();
                    }

                    return false;
                }

                @Override
                public void suspend() {
                }

                @Override
                public void resume() {
                }

                public static void main(String[] args) {
                    DesktopApplicationContext.main(Localization.class, args);
                }
            }
            ]]>
        </source>

        <p>
            The following example shows the application localized in German. Note that the applet
            is signed to allow the code to set the "user.language" system property:
        </p>

        <application class="org.apache.pivot.tutorials.localization.Localization"
            width="320" height="240">
            <libraries signed="true">
                <library>core</library>
                <library>wtk</library>
                <library>wtk-terra</library>
                <library>tutorials</library>
            </libraries>
            <startup-properties>
                <language>de</language>
            </startup-properties>
        </application>

        <p>
            Notice that the <tt>startup()</tt> method includes code to search for a font that can
            display a sample set of characters obtained from the "firstName" resource. This is
            because all fonts are not guaranteed to include support for all possible Unicode
            characters. If the current theme font is not capable of displaying the sample string,
            this block of code attempts to identify and set one that can. This code must be
            executed prior to constructing any user interface elements so that the correct font
            will be used.
        </p>
    </body>
</document>
