Skip to content

Commit 81991de

Browse files
committed
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.
1 parent 708fece commit 81991de

File tree

1 file changed

+25
-6
lines changed

1 file changed

+25
-6
lines changed

doc/api/intl.md

Lines changed: 25 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -113,27 +113,46 @@ This mode provides a balance between features and binary size.
113113

114114
If the `small-icu` option is used, one can still provide additional locale data
115115
at runtime so that the JS methods would work for all ICU locales. Assuming the
116-
data file is stored at `/some/directory`, it can be made available to ICU
117-
through either:
116+
data file is stored at `/runtime/directory/with/dat/file`, it can be made
117+
available to ICU through either:
118+
119+
* The `--with-icu-default-data-dir` configure option:
120+
121+
```bash
122+
./configure --with-icu-default-data-dir=/runtime/directory/with/dat/file --with-intl=small-icu
123+
```
124+
125+
This only embeds the default data directory path into the binary.
126+
The actual data file is going to be loaded at runtime from this directory path.
118127

119128
* The [`NODE_ICU_DATA`][] environment variable:
120129

121130
```bash
122-
env NODE_ICU_DATA=/some/directory node
131+
env NODE_ICU_DATA=/runtime/directory/with/dat/file node
123132
```
124133

125134
* The [`--icu-data-dir`][] CLI parameter:
126135

127136
```bash
128-
node --icu-data-dir=/some/directory
137+
node --icu-data-dir=/runtime/directory/with/dat/file
129138
```
130139

131-
(If both are specified, the `--icu-data-dir` CLI parameter takes precedence.)
140+
When more than one of them is specified, the `--icu-data-dir` CLI parameter has
141+
the highest precedence, then the `NODE_ICU_DATA` environment variable, then
142+
the `--with-icu-default-data-dir` configure option.
132143

133144
ICU is able to automatically find and load a variety of data formats, but the
134145
data must be appropriate for the ICU version, and the file correctly named.
135-
The most common name for the data file is `icudt6X[bl].dat`, where `6X` denotes
146+
The most common name for the data file is `icudtX[bl].dat`, where `X` denotes
136147
the intended ICU version, and `b` or `l` indicates the system's endianness.
148+
Node.js would fail to load if the expected data file cannot be read from the
149+
specified directory. The name of the data file corresponding to the current
150+
Node.js version can be computed with:
151+
152+
```js
153+
`icudt${process.versions.icu.split('.')[0]}${os.endianness()[0].toLowerCase()}.dat`;
154+
```
155+
137156
Check ["ICU Data"][] article in the ICU User Guide for other supported formats
138157
and more details on ICU data in general.
139158

0 commit comments

Comments
 (0)