---
layout: default
title: ICU Documentation
-nav_order: 1
+nav_order: 100
description: ICU Documentation
---
---
layout: default
title: Boundary Analysis
-nav_order: 12
+nav_order: 1300
has_children: true
---
<!--
---
layout: default
title: Collation
-nav_order: 11
+nav_order: 1200
has_children: true
---
<!--
---
layout: default
title: Conversion
-nav_order: 6
+nav_order: 700
has_children: true
---
<!--
---
layout: default
title: Date/Time
-nav_order: 8
+nav_order: 900
has_children: true
---
<!--
---
layout: default
title: Contributors
-nav_order: 17
+nav_order: 1800
has_children: true
---
<!--
---
layout: default
title: Formatting
-nav_order: 9
+nav_order: 1000
has_children: true
---
<!--
---
layout: default
title: ICU
-nav_order: 2
+nav_order: 300
has_children: true
---
<!--
> :point_right: **Note**: The ICU test suites _can_ be compiled with this setting.
* **.dat file:** By default, the ICU data is built into a shared library (DLL). This is convenient because it requires no install-time or runtime configuration, but the library is platform-specific and cannot be modified. A .dat package file makes the opposite trade-off: Platform-portable (except for endianness and charset family, which can be changed with the icupkg tool) and modifiable (also with the icupkg tool). If a path is set, then single data files (e.g., .res files) can be copied to that location to provide new locale data or conversion tables etc.
The only drawback with a .dat package file is that the application needs to provide ICU with the file system path to the package file (e.g., by calling `u_setDataDirectory()`) or with a pointer to the data (`udata_setCommonData()`) before other ICU API calls. This is usually easy if ICU is used from an application where `main()` takes care of such initialization. It may be hard if ICU is shipped with another shared library (such as the Xerces-C++ XML parser) which does not control `main()`.
- See the [User Guide ICU Data](https://unicode-org.github.io/icu/userguide/icudata) chapter for more details.
+ See the [User Guide ICU Data](../icu_data) chapter for more details.
If possible, we recommend building the .dat package. Specify `--with-data-packaging=archive` on the configure command line, as in
`runConfigureICU Linux --with-data-packaging=archive`
(Read the configure script's output for further instructions. On Windows, the Visual Studio build generates both the .dat package and the data DLL.)
### ICU as a System-Level Library
-If ICU is installed as a system-level library, there are further opportunities and restrictions to consider. For details, see the _Using ICU as an Operating System Level Library_ section of the [User Guide ICU Architectural Design](https://unicode-org.github.io/icu/userguide/design) chapter.
+If ICU is installed as a system-level library, there are further opportunities and restrictions to consider. For details, see the _Using ICU as an Operating System Level Library_ section of the [User Guide ICU Architectural Design](../icu/design) chapter.
* **Data path:** For a system-level library, it is best to load ICU data from the .dat package file because the file system path to the .dat package file can be hardcoded. ICU will automatically set the path to the final install location using `U_ICU_DATA_DEFAULT_DIR`. Alternatively, you can set `-DICU_DATA_DIR=/path/to/icu/data` when building the ICU code. (Used by source/common/putil.c.)
Consider also setting `-DICU_NO_USER_DATA_OVERRIDE` if you do not want the `ICU_DATA` environment variable to be used. (An application can still override the data path via `u_setDataDirectory()` or `udata_setCommonData()`.
---
layout: default
title: ICU4C
-nav_order: 3
+nav_order: 400
has_children: true
---
<!--
| ICU FAQ - Frequently Asked Questions about ICU | <https://unicode-org.github.io/icu/userguide/icu4c/faq> |
| ICU4J FAQ - Frequently Asked Questions about ICU4J | <https://unicode-org.github.io/icu/userguide/icu4j/faq> |
| ICU User's Guide | <https://unicode-org.github.io/icu/> |
-| How To Use ICU | <https://unicode-org.github.io/icu/userguide/howtouseicu> |
+| How To Use ICU | <https://unicode-org.github.io/icu/userguide/icu/howtouseicu> |
| Download ICU Releases | <http://site.icu-project.org/download> |
| ICU4C API Documentation Online | <http://icu-project.org/apiref/icu4c/> |
| Online ICU Demos | <http://demo.icu-project.org/icu-bin/icudemos> |
## ICU Source Code Organization
-In the descriptions below, `<ICU>` is the full path name of the ICU4C directory (the top level directory from the distribution archives) in your file system. You can also view the [ICU Architectural Design](design.md) section of the User's Guide to see which libraries you need for your software product. You need at least the data (`[lib]icudt`) and the common (`[lib]icuuc`) libraries in order to use ICU.
+In the descriptions below, `<ICU>` is the full path name of the ICU4C directory (the top level directory from the distribution archives) in your file system. You can also view the [ICU Architectural Design](../icu/design.md) section of the User's Guide to see which libraries you need for your software product. You need at least the data (`[lib]icudt`) and the common (`[lib]icuuc`) libraries in order to use ICU.
**The following files describe the code drop.**
environment variable to the out/ or the out/build/ directories, but
this is generally discouraged because most people set it incorrectly.
You can view the <a href=
- "https://unicode-org.github.io/icu/userguide/icudata">ICU Data
+ "https://unicode-org.github.io/icu/userguide/icu_data">ICU Data
Management</a> section of the ICU User's Guide for details.</p>
</td>
</tr>
For some people, it may not be necessary for completely build ICU. Most of the makefiles and build targets are for tools that are used for building ICU's data, and an application's data (when an application uses ICU resource bundles for its data).
-Data files can be built on a different platform when both platforms share the same endianness and the same charset family. This assertion does not include platform dependent DLLs/shared/static libraries. For details see the User Guide [ICU Data](https://unicode-org.github.io/icu/userguide/icudata) chapter.
+Data files can be built on a different platform when both platforms share the same endianness and the same charset family. This assertion does not include platform dependent DLLs/shared/static libraries. For details see the User Guide [ICU Data](../icu_data) chapter.
ICU 3.6 removes the requirement that ICU be completely built in the native operating environment. It adds the icupkg tool which can be run on any platform to turn binary ICU data files from any one of the three formats into any one of the other data formats. This allows a application to use ICU data built anywhere to be used for any other target platform.
distribution from conflicting with any libraries that you need. On operating systems
that do not have a standard C++ ABI (name mangling) for compilers, it is recommended to
do this special packaging anyway. More details on customizing ICU are available in the
-[User's Guide](https://unicode-org.github.io/icu/userguide/).
+[User Guide](../).
The [ICU Source Code Organization](./index/#icu-source-code-organization) section of
the ICU4C gives a more complete description of the libraries.
| Library Name | Windows Filename | Linux Filename | Comment |
|-------------------------------------|------------------|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Data Library | icudtXYl.dll | libicudata.so.XY.Z | Data required by the Common and I18n libraries. There are many ways to package and [customize this data](https://unicode-org.github.io/icu/userguide/icudata), but by default this is all you need. |
+| Data Library | icudtXYl.dll | libicudata.so.XY.Z | Data required by the Common and I18n libraries. There are many ways to package and [customize this data](../icu_data), but by default this is all you need. |
| Common Library | icuucXY.dll | libicuuc.so.XY.Z | Base library required by all other ICU libraries. |
| Internationalization (i18n) Library | icuinXY.dll | libicui18n.so.XY.Z | A library that contains many locale based internationalization (i18n) functions. |
| Layout Extensions Engine | iculxXY.dll | libiculx.so.XY.Z | An optional engine for doing paragraph layout that uses parts of ICU. HarfBuzz is required. |
---
layout: default
title: ICU4J
-nav_order: 4
+nav_order: 500
has_children: true
---
<!--
ICU4J is an add-on to the regular JRE that provides:
-* [Collation](https://unicode-org.github.io/icu/userguide/collation) – rule-based, up-to-date Unicode Collation Algorithm (UCA) sorting order
+* [Collation](../collation) – rule-based, up-to-date Unicode Collation Algorithm (UCA) sorting order
For fast multilingual string comparison; faster and more complete than the J2SE implementation
-* [Charset Detection](https://unicode-org.github.io/icu/userguide/conversion/detection) – Recognition of various single and multibyte charsets
+* [Charset Detection](../conversion/detection) – Recognition of various single and multibyte charsets
Useful for recognizing untagged text data
-* [UnicodeSet](https://unicode-org.github.io/icu/userguide/strings/unicodeset) – standard set operations optimized for sets of Unicode characters
+* [UnicodeSet](../strings/unicodeset) – standard set operations optimized for sets of Unicode characters
UnicodeSets can be built from string patterns using any Unicode properties.
-* [Transforms](https://unicode-org.github.io/icu/userguide/transforms) – a flexible mechanism for Unicode text conversions
+* [Transforms](../transforms) – a flexible mechanism for Unicode text conversions
Including Full/Halfwidth conversions, Normalization, Case conversions, Hex conversions, and transliterations between scripts (50+ pairs)
-* [Unicode Normalization](https://unicode-org.github.io/icu/userguide/transforms/normalization) – NFC, NFD, NFKD, NFKC
+* [Unicode Normalization](../transforms/normalization) – NFC, NFD, NFKD, NFKC
For canonical text representations, needed for XML and the net
-* [International Calendars](https://unicode-org.github.io/icu/userguide/datetime/calendar) – Arabic, Buddhist, Chinese, Hebrew, Japanese, Ethiopic, Islamic, Coptic and other calendars
+* [International Calendars](../datetime/calendar) – Arabic, Buddhist, Chinese, Hebrew, Japanese, Ethiopic, Islamic, Coptic and other calendars
Required for correct presentation of dates in certain countries
-* [Date Format Enhancements](https://unicode-org.github.io/icu/userguide/format_parse/datetime) – Date/time pattern generator, Relative date formatting, etc.
+* [Date Format Enhancements](../format_parse/datetime) – Date/time pattern generator, Relative date formatting, etc.
Enhancements to the normal Java date formatting.
-* [Number Format Enhancements](https://unicode-org.github.io/icu/userguide/format_parse/numbers) – Scientific Notation, Spelled-out, Compact decimal format, etc.
+* [Number Format Enhancements](../format_parse/numbers) – Scientific Notation, Spelled-out, Compact decimal format, etc.
Enhancements to the normal Java number formatting. The spell-out format is used for checks and similar documents
-* [Enhanced Word-Break Detection](https://unicode-org.github.io/icu/userguide/boundaryanalysis) – Rule-based, supports Thai, Khmer, Chinese, etc.
+* [Enhanced Word-Break Detection](../boundaryanalysis) – Rule-based, supports Thai, Khmer, Chinese, etc.
Required for correct support of Thai
-* [Unicode Text Compression](https://unicode-org.github.io/icu/userguide/conversion/compression) – Standard compression of Unicode text
+* [Unicode Text Compression](../conversion/compression) – Standard compression of Unicode text
Suitable for large numbers of small fields, where LZW and similar schemes do not apply
-* [Charset Conversion](https://unicode-org.github.io/icu/userguide/conversion) – Conversion to and from different charsets.
+* [Charset Conversion](../conversion) – Conversion to and from different charsets.
Plugs into Java CharsetProvider Service Provider Interface (SPI)
> :point_right: **Note:** We continue to provide assistance to Java, and in some cases, ICU4J support has been rolled into a later release of Java. For example, BCP47 language tag support including Unicode locale extensions is now in Java 7\. However, the most current and complete version is always found in ICU4J.
## Where to get Documentation
-The [ICU user's guide](https://unicode-org.github.io/icu/userguide/) contains lots of general information about ICU, in its C, C++, and Java incarnations.
+The [ICU User Guide](../) contains lots of general information about ICU, in its C, C++, and Java incarnations.
The complete API documentation for ICU4J (javadoc) is available on the ICU4J web site, and can be built from the sources:
## About ICU4J Time Zone
-ICU4J library includes the latest time zone data, as of the release date. However, time zone data is frequently updated in response to changes made by local governments around the world. If you need to update the time zone data, please refer the ICU user guide topic [Updating the Time Zone Data](https://unicode-org.github.io/icu/userguide/datetime/timezone#updating-the-time-zone-data).
+ICU4J library includes the latest time zone data, as of the release date. However, time zone data is frequently updated in response to changes made by local governments around the world. If you need to update the time zone data, please refer the ICU user guide topic [Updating the Time Zone Data](../datetime/timezone#updating-the-time-zone-data).
You can optionally configure ICU4J date and time service classes to use underlying JDK TimeZone implementation (see the ICU4J API reference [TimeZone](https://unicode-org.github.io/icu-docs/apidoc/released/icu4j/com/ibm/icu/util/TimeZone.html) for the details). When this configuration is enabled, ICU's own time zone data won't be used and you have to get time zone data patches from the JRE vendor.
---
layout: default
title: ICU Data
-nav_order: 15
+nav_order: 1600
has_children: true
---
<!--
3. Dynamically load (memory map, typically) a common format (.dat) file
containing the default ICU data. Loading is described in the section
- [How Data Loading Works](icudata#how-data-loading-works). The path to
+ [How Data Loading Works](#how-data-loading-works). The path to
the data is of the form "icudt\<version\>\<flag\>", where \<version\> is
the two-digit ICU version number, and \<flag\> is a letter indicating the
internal format of the file (see the
- [Sharing ICU Data Between Platforms](icudata#sharing-icu-data-between-platforms)
+ [Sharing ICU Data Between Platforms](#sharing-icu-data-between-platforms)
section).
Once the default ICU data has been located, loading of individual data items
proceeds as described in the section
-[How Data Loading Works](icudata#how-data-loading-works).
+[How Data Loading Works](#how-data-loading-works).
## Building and Linking against ICU data
in a known location that is included in the ICU data directory string. This
requires the application installer, or the application itself at runtime, to
locate the ICU and/or application data by setting the ICU data directory (see
-the [ICU Data Directory](icudata#icu-data-directory) section above) or by
+the [ICU Data Directory](#icu-data-directory) section above) or by
loading the data and providing it to one of the `udata_setXYZData()` functions.
Unlike shared libraries, .dat package files can be taken apart into separate
used to reassemble the .dat package file.
For more information about .dat package files see the section [Sharing ICU Data
-Between Platforms](icudata#sharing-icu-data-between-platforms) below.
+Between Platforms](#sharing-icu-data-between-platforms) below.
### Data Overriding vs. Loading Performance
already-loaded package files. This allows overriding of packaged data items with
single files after installation but costs some time for filesystem accesses.
This is usually done only once per data item; see
-[User Data Caching](icudata#user-data-caching) below.
+[User Data Caching](#user-data-caching) below.
### Single Data Files vs. Packages
> :point_right: **Note**: The ICU data directory string itself may
contain multiple directories and path/filenames to .dat package files. See the
-[ICU Data Directory](icudata#icu-data-directory) section.
+[ICU Data Directory](#icu-data-directory) section.
It is recommended to not include the directory in the path argument but to make
sure via setting the application data or the ICU data directory string that the
--- /dev/null
+---
+layout: default
+title: ICU User Guide
+nav_order: 200
+description: ICU User Guide
+---
+
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# ICU User Guide
+
+[](http://site.icu-project.org/)
+
+This User Guide provides information on i18n topics for which ICU has services, and
+includes details that go beyond the C, C++, and Java API docs (and avoids some duplication between them).
+
+You may want to start with the [Introduction to ICU](./icu) or browse the navigation bar for a specific topic.
+
+This is the new home of the User Guide (since 2020 August).
---
layout: default
title: IO
-nav_order: 13
+nav_order: 1400
has_children: true
---
<!--
---
layout: default
title: Layout Engine
-nav_order: 14
+nav_order: 1500
has_children: true
---
<!--
---
layout: default
title: Locales and Resources
-nav_order: 7
+nav_order: 800
has_children: true
---
<!--
---
layout: default
title: Chars and Strings
-nav_order: 5
+nav_order: 600
has_children: true
---
<!--
---
layout: default
title: Transforms
-nav_order: 10
+nav_order: 1100
has_children: true
---
<!--
---
layout: default
title: Use From...
-nav_order: 16
+nav_order: 1700
has_children: true
---
<!--
projects / icu / commitdiff