1// 2// Copyright (c) 2009-2011 Artyom Beilis (Tonkikh) 3// 4// Distributed under the Boost Software License, Version 1.0. (See 5// accompanying file LICENSE_1_0.txt or copy at 6// http://www.boost.org/LICENSE_1_0.txt) 7// 8 9// vim: tabstop=4 expandtab shiftwidth=4 softtabstop=4 filetype=cpp.doxygen 10/*! 11\page locale_gen Locale Generation 12 13Each locale is defined by a specific locale identifier, which contains a mandatory part (Language) and several optional parts 14(Country, Variant, keywords and character encoding of \c std::string). Boost.Locale uses the POSIX naming convention for locales, 15i.e. a locale is defined as <tt>language[_COUNTRY][.encoding][\@variant]</tt>, where lang is ISO-639 language name like "en" or "ru", 16COUNTRY is the ISO-3166 country identifier like "US" or "DE", encoding is the eight-bit character encoding like \c UTF-8 or \c ISO-8859-1, 17and variant is additional options for specializing the locale, like \c euro or \c calendar=hebrew, see \ref locale_gen_variant. 18 19Note that each locale should include the encoding in order to handle \c char based strings correctly. 20 21\section locale_gen_basics Basics 22 23The class \ref boost::locale::generator "generator" provides tools to generate the locales we need. The simplest way to use 24\c generator is to create a locale and set it as the global one: 25 26\code 27 #include <boost/locale.hpp> 28 29 using namespace boost::locale; 30 int main() 31 { 32 generator gen; 33 // Create locale generator 34 std::locale::global(gen("")); 35 // "" - the system default locale, set 36 // it globally 37 } 38\endcode 39 40Of course we can also specify the locale manually 41 42\code 43 std::locale loc = gen("en_US.UTF-8"); 44 // Use English, United States locale 45\endcode 46 47\note 48 49- Even if your application uses wide strings everywhere, you should specify the 50 8-bit encoding to use for 8-bit stream IO operations like \c cout or \c fstream. 51 \n 52- The default locale is defined by the environment variables \c LC_CTYPE , \c LC_ALL , and \c LANG 53 in that order (i.e. \c LC_CTYPE first and \c LANG last). On Windows, the library 54 also queries the \c LOCALE_USER_DEFAULT option in the Win32 API when these variables 55 are not set. 56 57\b Tip: Prefer using UTF-8 Unicode encoding over 8-bit encodings like the ISO-8859-X ones. 58 59By default the generated locales include all supported categories and character types. However, if your 60application uses only 8-bit encodings, only wide-character encodings, or only specific facets, you can 61limit the facet generation to specific categories and character types by calling the 62\ref boost::locale::generator::categories() "categories" and \ref boost::locale::generator::characters() "characters" 63member functions of the \ref boost::locale::generator "generator" class. 64 65For example: 66 67\code 68 generator gen; 69 gen.characters(wchar_t_facet); 70 gen.categories(collation_facet | formatting_facet); 71 std::locale::global(gen("de_DE.UTF-8")); 72\endcode 73 74\section locale_gen_variant Variant 75 76The variant part of the locale (the part that comes after \@ symbol) is localization \ref using_localization_backends "back-end" dependent. 77 78\subsection locale_gen_variant_non_icu Non ICU Backends 79 80\ref posix_backend "POSIX" and \ref std_backend "std" back-ends use their own OS specific naming conventions and 81depend on the current OS configuration. For example typical Linux distribution provides \c euro for currency selection, 82\c cyrillic and \c latin for specification of language script. 83 84\ref winapi_backend "winapi" back-end does not support any variants. 85 86\subsection locale_gen_variant_icu ICU Backend 87 88ICU provides wide range of locale variant options. For detailed instructions read <a href="http://userguide.icu-project.org/locale">this</a> 89ICU manual pages. 90 91However in general it is represented as set of key=value pairs separated with a semicolon ";" For example: 92"@collation=phonebook;calendar=islamic-civil". 93 94Currently ICU supports following keys: 95 96- \c calendar - the calendar used for the current locale. For example: \c gregorian, \c japanese, 97 \c buddhist, \c islamic, \c hebrew, \c chinese, \c islamic-civil. 98- \c collation - the collation order used for this locales, for example \c phonebook, \c pinyin, \c traditional, 99 \c stroke, \c direct, \c posix. 100- \c currency - the currency used in this locale, the standard 3 letter code like USD or JPY. 101- \c numbers - the numbering system used, for example: \c latn, \c arab, \c thai. 102 103Please refer to CLDR and ICU documentation for exact list of keys and values: 104 105- <a href="http://userguide.icu-project.org/locale#TOC-Keywords">ICU User Guide/Locale/Keywords</a> 106- <a href="http://www.unicode.org/reports/tr35/">Unicode Locale Data Markup Language</a> 107 108 109*/ 110 111