From e0f93492d5c2418ddfc53de3ef496de15eb311be Mon Sep 17 00:00:00 2001 From: Joyee Cheung Date: Fri, 15 Sep 2023 15:25:36 +0200 Subject: [PATCH] doc: improve documentation about ICU data fallback This patch: - Documents `--with-icu-default-data-dir` and its precedence - Elaborates a bit more about the format of the name of the expected data file. PR-URL: https://github.com/nodejs/node/pull/49666 Reviewed-By: Richard Lau Reviewed-By: James M Snell --- doc/api/intl.md | 32 ++++++++++++++++++++++++++------ 1 file changed, 26 insertions(+), 6 deletions(-) diff --git a/doc/api/intl.md b/doc/api/intl.md index 3af63ae8a19bd7..ec3e26db3b4c1e 100644 --- a/doc/api/intl.md +++ b/doc/api/intl.md @@ -113,27 +113,47 @@ This mode provides a balance between features and binary size. If the `small-icu` option is used, one can still provide additional locale data at runtime so that the JS methods would work for all ICU locales. Assuming the -data file is stored at `/some/directory`, it can be made available to ICU -through either: +data file is stored at `/runtime/directory/with/dat/file`, it can be made +available to ICU through either: + +* The `--with-icu-default-data-dir` configure option: + + ```bash + ./configure --with-icu-default-data-dir=/runtime/directory/with/dat/file --with-intl=small-icu + ``` + + This only embeds the default data directory path into the binary. + The actual data file is going to be loaded at runtime from this directory + path. * The [`NODE_ICU_DATA`][] environment variable: ```bash - env NODE_ICU_DATA=/some/directory node + env NODE_ICU_DATA=/runtime/directory/with/dat/file node ``` * The [`--icu-data-dir`][] CLI parameter: ```bash - node --icu-data-dir=/some/directory + node --icu-data-dir=/runtime/directory/with/dat/file ``` -(If both are specified, the `--icu-data-dir` CLI parameter takes precedence.) +When more than one of them is specified, the `--icu-data-dir` CLI parameter has +the highest precedence, then the `NODE_ICU_DATA` environment variable, then +the `--with-icu-default-data-dir` configure option. ICU is able to automatically find and load a variety of data formats, but the data must be appropriate for the ICU version, and the file correctly named. -The most common name for the data file is `icudt6X[bl].dat`, where `6X` denotes +The most common name for the data file is `icudtX[bl].dat`, where `X` denotes the intended ICU version, and `b` or `l` indicates the system's endianness. +Node.js would fail to load if the expected data file cannot be read from the +specified directory. The name of the data file corresponding to the current +Node.js version can be computed with: + +```js +`icudt${process.versions.icu.split('.')[0]}${os.endianness()[0].toLowerCase()}.dat`; +``` + Check ["ICU Data"][] article in the ICU User Guide for other supported formats and more details on ICU data in general.