Qt.locale() and JS locale type extension.

Task-number: QTBUG-17129

Change-Id: I69cbbe858735b750b4e37ce489f2fa1ad5d8b5d3
Reviewed-by: Martin Jones <martin.jones@nokia.com>

doc/src/declarative/qdeclarativei18n.qdoc

@@ -34,6 +34,7 @@
 \nextpage {QML Features}
 \title QML Internationalization
 
+\section1 Translation
 
 Strings in QML can be marked for translation using the qsTr(), qsTranslate(),
 QT_TR_NOOP(), and QT_TRANSLATE_NOOP() functions.
@@ -55,14 +56,14 @@ capabilities are described more fully in:
 
 You can test a translation with the \l {QML Viewer} using the -translation option.
 
-\section1 Example
+\section2 Example
 
 First we create a simple QML file with text to be translated. The string
 that needs to be translated is enclosed in a call to \c qsTr().
 
 hello.qml:
 \qml
-import QtQuick 1.0
+import QtQuick 2.0
 
 Rectangle {
     width: 200; height: 200
@@ -83,6 +84,15 @@ Finally, we can test the translation:
 qmlviewer -translation hello.qm hello.qml
 \endcode
 
-
 You can see a complete example and source code in the \l{declarative/i18n}{QML Internationalization example}.
+
+\section1 Localization
+
+Localization is the process of adapting to local conventions,
+for example presenting dates and times using the locally preferred formats.
+
+Qt Quick supports localization via the \l {QtQuick2::Locale}{Locale} object and extensions to the
+ECMAScript \l {QtQuick2::Date}{Date} and \l {QtQuick2::Number}{Number} types.
+
+
 */

doc/src/declarative/qmldate.qdoc

@@ -0,0 +1,149 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \qmlclass Date
+    \inqmlmodule QtQuick 2
+    \brief The Date object provides date functions
+
+    The QML Date object extends the JS Date object with
+    locale aware functions.
+
+    Functions that accept a locale format may be either an enumeration
+    value:
+    \table
+    \row \i Locale.LongFormat \i The long version of day and month names; for example, returning "January" as a month name.
+    \row \i Locale.ShortFormat \i The short version of day and month names; for example, returning "Jan" as a month name.
+    \row \i Locale.NarrowFormat \i A special version of day and month names for use when space is limited;
+        for example, returning "J" as a month name. Note that the narrow format might contain
+        the same text for different months and days or it can even be an empty string if the
+        locale doesn't support narrow names, so you should avoid using it for date formatting.
+        Also, for the system locale this format is the same as ShortFormat.
+    \endtable
+
+    or a string specifying the format:
+    \table
+    \header \i Expression \i Output
+    \row \i d \i the day as number without a leading zero (1 to 31)
+    \row \i dd \i the day as number with a leading zero (01 to 31)
+    \row \i ddd
+         \i the abbreviated localized day name (e.g. 'Mon' to 'Sun').
+    \row \i dddd
+         \i the long localized day name (e.g. 'Monday' to 'Sunday').
+    \row \i M \i the month as number without a leading zero (1 to 12)
+    \row \i MM \i the month as number with a leading zero (01 to 12)
+    \row \i MMM
+         \i the abbreviated localized month name (e.g. 'Jan' to 'Dec').
+    \row \i MMMM
+         \i the long localized month name (e.g. 'January' to 'December').
+    \row \i yy \i the year as two digit number (00 to 99)
+    \row \i yyyy \i the year as four digit number. If the year is negative,
+            a minus sign is prepended in addition.
+    \endtable
+
+    All other input characters will be ignored. Any sequence of characters that
+    are enclosed in singlequotes will be treated as text and not be used as an
+    expression. Two consecutive singlequotes ("''") are replaced by a singlequote
+    in the output.
+
+    Example format strings (assuming that the Date is the 20 July
+    1969):
+
+    \table
+    \header \o Format            \o Result
+    \row    \o dd.MM.yyyy        \o 20.07.1969
+    \row    \o ddd MMMM d yy     \o Sun July 20 69
+    \row    \o 'The day is' dddd \o The day is Sunday
+    \endtable
+
+    \sa {QtQuick2::Locale}{Locale}
+*/
+
+/*!
+    \qmlmethod string Date::toLocaleString(locale,format)
+
+    Converts the Date to a string containing the date and time
+    suitable for the specified \a locale
+    in the specified \a format.
+
+    If the format is not specified Locale.LongFormat will be used.
+
+    If \a locale is not specified, the default locale will be used.
+
+    The following example shows the current date and time formatted
+    for the German locale:
+    \code
+    import QtQuick 2.0
+
+    Text {
+        text: "The date is: " +  Date().toLocaleString(Qt.locale("de_DE"))
+    }
+    \endcode
+*/
+
+/*!
+    \qmlmethod string Date::toLocaleDateString(locale,format)
+
+    Converts the Date to a string containing the date suitable for the specified \a locale
+    in the specified \a format.
+
+    If the format is not specified Locale.LongFormat will be used.
+
+    If \a locale is not specified, the default locale will be used.
+
+    The following example shows the current date formatted
+    for the German locale:
+    \code
+    import QtQuick 2.0
+
+    Text {
+        text: "The date is: " +  Date().toLocaleDateString(Qt.locale("de_DE"))
+    }
+    \endcode
+*/
+
+/*!
+    \qmlmethod string Date::toLocaleTimeString(locale,format)
+
+    Converts the Date to a string containing the time suitable for the specified \a locale
+    in the specified \a format.
+
+    If the format is not specified Locale.LongFormat will be used.
+
+    If \a locale is not specified, the default locale will be used.
+
+    The following example shows the current time formatted
+    for the German locale:
+    \code
+    import QtQuick 2.0
+
+    Text {
+        text: "The date is: " +  Date().toLocaleTimeString(Qt.locale("de_DE"))
+    }
+    \endcode
+*/
+

doc/src/declarative/qmlnumber.qdoc

@@ -0,0 +1,105 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \qmlclass Number
+    \inqmlmodule QtQuick 2
+    \brief The Number object provides represents a number value
+
+    The QML Number object extends the JS Number object with
+    locale aware functions.
+
+    \sa {QtQuick2::Locale}{Locale}
+*/
+
+/*!
+    \qmlmethod string Number::toLocaleString(locale,format,precision)
+
+    Converts the Number to a string suitable for the specified \a locale
+    in the specified \a format, with the specified \a precision.
+
+    Valid formats are:
+    \list
+    \o 'f'   Decimal floating point, e.g. 248.65
+    \o 'e'   Scientific notation using e character, e.g. 2.4865e+2
+    \o 'E'   Scientific notation using E character, e.g. 2.4865E+2
+    \o 'g'   Use the shorter of e or f
+    \o 'G'   Use the shorter of E or f
+    \endlist
+
+    If precision is not specified, the precision will be 2.
+
+    If the format is not specified 'f' will be used.
+
+    If \a locale is not specified, the default locale will be used.
+
+    The following example shows a number formatted for the German locale:
+    \code
+    import QtQuick 2.0
+
+    Text {
+        text: "The value is: " +  Number(4742378.423).toLocaleString(Qt.locale("de_DE"))
+    }
+    \endcode
+
+    You can apply toLocaleString() directly to constants, provided the decimal
+    is included in the constant, e.g.
+    \code
+    123.0.toLocaleString(Qt.locale("de_DE")) // OK
+    123..toLocaleString(Qt.locale("de_DE"))  // OK
+    123.toLocaleString(Qt.locale("de_DE"))   // fails
+    \endcode
+*/
+
+/*!
+    \qmlmethod string Number::toLocaleCurrencyString(locale,symbol)
+
+    Converts the Number to a currency using the currency and conventions of the specified
+    \a locale.  If \a symbol is specified it will be used as the currency
+    symbol.
+
+    \sa Locale::currencySymbol()
+*/
+
+/*!
+    \qmlmethod string Number::fromLocaleString(locale,number)
+
+    Returns a Number by parsing \a number using the conventions of the supplied \a locale.
+
+    If \a locale is not supplied the default locale will be used.
+
+    For example, using the German locale:
+    \code
+    var german = Qt.locale("de_DE");
+    var d;
+    d = Number.fromLocaleString(german, "1234,56)   // d == 1234.56
+    d = Number.fromLocaleString(german, "1.234,56") // d == 1234.56
+    d = Number.fromLocaleString(german, "1234.56")  // throws exception
+    d = Number.fromLocaleString(german, "1.234")    // d == 1234.0
+    \endcode
+*/
+

doc/src/qtquick1/declarativeui.qdoc

@@ -77,7 +77,7 @@ Qt applications.
 \o \l{Integrating QML Code with Existing Qt UI Code}
 \o \l{Dynamic Object Management in QML}{Dynamic Object Management}
 \o \l{Network Transparency}{Loading Resources in QML}
-\o \l{QML Internationalization}{Internationalization}
+\o \l{QML Internationalization}{Qt Quick 1 Internationalization}
 \endlist
 
 \section1 QML Add-Ons

doc/src/qtquick1/qdeclarativei18n.qdoc

@@ -32,7 +32,7 @@
 \contentspage QML Features
 \previouspage {Network Transparency}{Loading Resources in QML}
 \nextpage {QML Features}
-\title QML Internationalization
+\title Qt Quick 1 Internationalization
 
 
 Strings in QML can be marked for translation using the qsTr(), qsTranslate(),