Skip to content

Commit 9930311

Browse files
wooormwooorm
committed
Add improved docs
1 parent 4c244c1 commit 9930311

File tree

7 files changed

+138
-110
lines changed

7 files changed

+138
-110
lines changed

‎packages/franc-all/readme.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,26 +2,26 @@
22

33
# franc-all
44

5-
> Detect the language of text.
5+
Detect the language of text.
66

77
Built with support for 414 languages.
88

99
View the [monorepo](https://github.com/wooorm/franc) for more packages and
10-
usage information.
10+
info on using them.
1111

1212
## Install
1313

14-
This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c):
15-
Node 12+ is needed to use it and it must be
16-
`import`ed instead of `require`d.
14+
This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).
15+
In Node.js (version 14.14+, 16.0+), install with
16+
[npm](https://docs.npmjs.com/cli/install):
1717

1818
npm:
1919

2020
```sh
2121
npm install franc-all
2222
```
2323

24-
## Support
24+
## Data
2525

2626
This build supports the following languages:
2727

‎packages/franc-cli/readme.md‎

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,6 @@ and usage information.
77

88
## Install
99

10-
This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c):
11-
Node 12+ is needed to use it.
12-
13-
npm:
14-
1510
```sh
1611
npm install franc-cli --global
1712
```

‎packages/franc-min/readme.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,26 +2,26 @@
22

33
# franc-min
44

5-
> Detect the language of text.
5+
Detect the language of text.
66

77
Built with support for 82 languages (8M or more speakers).
88

99
View the [monorepo](https://github.com/wooorm/franc) for more packages and
10-
usage information.
10+
info on using them.
1111

1212
## Install
1313

14-
This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c):
15-
Node 12+ is needed to use it and it must be
16-
`import`ed instead of `require`d.
14+
This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).
15+
In Node.js (version 14.14+, 16.0+), install with
16+
[npm](https://docs.npmjs.com/cli/install):
1717

1818
npm:
1919

2020
```sh
2121
npm install franc-min
2222
```
2323

24-
## Support
24+
## Data
2525

2626
This build supports the following languages:
2727

‎packages/franc/index.js‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,11 @@
33
*
44
* @typedef Options
55
* @property {Array<string>} [only]
6-
* allow languages
6+
* Languages to allow.
77
* @property {Array<string>} [ignore]
8-
* disallow languages
8+
* Languages to ignore.
99
* @property {number} [minLength=10]
10-
* minimum length to accept
10+
* Minimum length to accept.
1111
*/
1212

1313
/* Load `trigram-utils`. */

‎packages/franc/readme.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,26 +2,26 @@
22

33
# franc
44

5-
> Detect the language of text.
5+
Detect the language of text.
66

77
Built with support for 186 languages (1M or more speakers).
88

99
View the [monorepo](https://github.com/wooorm/franc) for more packages and
10-
usage information.
10+
info on using them.
1111

1212
## Install
1313

14-
This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c):
15-
Node 12+ is needed to use it and it must be
16-
`import`ed instead of `require`d.
14+
This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).
15+
In Node.js (version 14.14+, 16.0+), install with
16+
[npm](https://docs.npmjs.com/cli/install):
1717

1818
npm:
1919

2020
```sh
2121
npm install franc
2222
```
2323

24-
## Support
24+
## Data
2525

2626
This build supports the following languages:
2727

‎readme.md‎

Lines changed: 106 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,8 @@ Detect the language of text.
1313
languages
1414
3. **franc** has a CLI
1515

16-
† - Based on the [UDHR][], the most translated document in the world.
16+
† - Based on the [UDHR][], the most translated copyright-free document in the
17+
world.
1718

1819
## What’s not so cool about franc?
1920

@@ -23,97 +24,104 @@ Make sure to pass it big documents to get reliable results.
2324

2425
## Install
2526

26-
This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c):
27-
Node 12+ is needed to use it and it must be `import`ed instead of `require`d.
27+
> 👉 **Note**: this installs the [`franc`][m] package, with support for 187
28+
> languages (languages which have 1 million or more speakers).
29+
> [`franc-min`][s] (82 languages, 8m or more speakers) and [`franc-all`][l]
30+
> (all 414 possible languages) are also available.
31+
> Finally, use `franc-cli` to install the [CLI][].
2832
29-
[npm][]:
33+
This package is [ESM only][esm].
34+
In Node.js (version 14.14+, 16.0+), install with [npm][]:
3035

3136
```sh
3237
npm install franc
3338
```
3439

35-
This installs the [`franc`][m] package, with support for 187 languages
36-
(languages which have 1 million or more speakers).
37-
[`franc-min`][s] (82 languages, 8m or more speakers) and [`franc-all`][l] (all
38-
414 possible languages) are also available.
39-
Finally, use `franc-cli` to install the [CLI][].
40+
In Deno with [`esm.sh`][esmsh]:
4041

41-
Browser builds for [`franc-min`][s], [`franc`][m], and [`franc-all`][l] are
42-
available on [GitHub Releases][releases].
42+
```js
43+
import {franc, francAll} from 'https://esm.sh/franc@6'
44+
```
4345

44-
## Use
46+
In browsers with [`esm.sh`][esmsh]:
4547

46-
This package exports the following identifiers: `franc`, `francAll`.
47-
There is no default export.
48+
```html
49+
<script type="module">
50+
import {franc, francAll} from 'https://esm.sh/franc@6?bundle'
51+
</script>
52+
```
53+
54+
## Use
4855

4956
```js
5057
import {franc, francAll} from 'franc'
5158

52-
franc('Alle menslike wesens word vry') // => 'afr'
53-
franc('এটি একটি ভাষা একক IBM স্ক্রিপ্ট') // => 'ben'
54-
franc('Alle menneske er fødde til fridom') // => 'nno'
59+
franc('Alle menslike wesens word vry') //=> 'afr'
60+
franc('এটি একটি ভাষা একক IBM স্ক্রিপ্ট') //=> 'ben'
61+
franc('Alle menneske er fødde til fridom') //=> 'nno'
5562

56-
franc('') // => 'und' (language code that stands for undetermined)
63+
franc('') //=> 'und' (language code that stands for undetermined)
5764

5865
// You can change what’s too short (default: 10):
59-
franc('the') // => 'und'
60-
franc('the', {minLength: 3}) // => 'sco'
61-
```
62-
63-
###### `francAll`
66+
franc('the') //=> 'und'
67+
franc('the', {minLength: 3}) //=> 'sco'
6468

65-
```js
6669
console.log(francAll('Considerando ser essencial que os direitos humanos'))
67-
```
70+
//=> [['por', 1], ['glg', 0.771284519307895], ['spa', 0.6034146900423971], …123 more items]
6871

69-
Yields:
72+
console.log(francAll('Considerando ser essencial que os direitos humanos', {only: ['por', 'spa']}))
73+
//=> [['por', 1 ], ['spa', 0.6034146900423971]]
7074

71-
```js
72-
[
73-
[ 'por', 1 ],
74-
[ 'glg', 0.771284519307895 ],
75-
[ 'spa', 0.6034146900423971 ],
76-
[ 'cat', 0.5367251059928957 ],
77-
[ 'src', 0.47461899851037015 ],
78-
... 122 more items ]
75+
console.log(francAll('Considerando ser essencial que os direitos humanos', {ignore: ['spa', 'glg']}))
76+
//=> [['por', 1], ['cat', 0.5367251059928957], ['src', 0.47461899851037015], …121 more items]
7977
```
8078

81-
###### `only`
79+
## API
8280

83-
```js
84-
console.log(
85-
francAll('Considerando ser essencial que os direitos humanos', {
86-
only: ['por', 'spa']
87-
})
88-
)
89-
```
81+
This package exports the identifiers `franc`, `francAll`.
82+
There is no default export.
9083

91-
Yields:
84+
### `franc(value[, options])`
9285

93-
```js
94-
[ [ 'por', 1 ], [ 'spa', 0.6034146900423971 ] ]
95-
```
86+
Get the most probable language for the given value.
9687

97-
###### `ignore`
88+
###### Parameters
9889

99-
```js
100-
console.log(
101-
francAll('Considerando ser essencial que os direitos humanos', {
102-
ignore: ['src', 'glg']
103-
})
104-
)
105-
```
90+
* `value` (`string`) — value to test
91+
* `options` (`Options`, optional) — configuration
10692

107-
Yields:
93+
###### Returns
10894

109-
```js
110-
[ [ 'por', 1 ],
111-
[ 'spa', 0.6034146900423971 ],
112-
[ 'cat', 0.5367251059928957 ],
113-
[ 'ita', 0.4740460639394981 ],
114-
[ 'fra', 0.44757648676521145 ],
115-
... 120 more items ]
116-
```
95+
The most probable language (`string`).
96+
97+
### `francAll(value[, options])`
98+
99+
Get the most probable language for the given value.
100+
101+
###### Parameters
102+
103+
* `value` (`string`) — value to test
104+
* `options` (`Options`, optional) — configuration
105+
106+
###### Returns
107+
108+
Array containing language—distance tuples (`Array<[string, number]>`).
109+
110+
### `Options`
111+
112+
Configuration (`Object`, optional) with the following fields:
113+
114+
###### `options.only`
115+
116+
Languages to allow (`Array<string>`, optional).
117+
118+
###### `options.ignore`
119+
120+
Languages to ignore (`Array<string>`, optional).
121+
122+
###### `options.minLength`
123+
124+
Minimum length to accept (`number`, default: `10`).
117125

118126
## CLI
119127

@@ -158,26 +166,39 @@ $ echo "Alle mennesker er født frie og" | franc --only nob,dan
158166
# nob
159167
```
160168

161-
## Supported languages
169+
## Data
170+
171+
###### Supported languages
162172

163173
| Package | Languages | Speakers |
164174
| - | - | - |
165175
| [`franc-min`][s] | 82 | 8M or more |
166176
| [`franc`][m] | 187 | 1M or more |
167177
| [`franc-all`][l] | 414 | - |
168178

169-
### Language code
179+
###### Language code
170180

171-
Note that franc returns [ISO 639-3][iso6393] codes (three letter codes).
172-
**Not** ISO 639-1 or ISO 639-2.
173-
See also [GH-10][] and [GH-30][].
181+
> 👉 **Note**: franc returns [ISO 639-3][iso6393] codes (three letter codes).
182+
> **Not** ISO 639-1 or ISO 639-2.
183+
> See also [GH-10][] and [GH-30][].
174184
175185
To get more info about the languages represented by ISO 639-3, use
176186
[`iso-639-3`][iso-639-3].
177187
There is also an index available to map ISO 639-3 to ISO 639-1 codes,
178188
[`iso-639-3/to-1.json`][iso-639-3-to-1], but note that not all 639-3 codes can
179189
be represented in 639-1.
180190

191+
## Types
192+
193+
These packages are fully typed with [TypeScript][].
194+
They export the additional types `TrigramTuple` and `Options`.
195+
196+
## Compatibility
197+
198+
These package are at least compatible with all maintained versions of Node.js.
199+
As of now, that is Node.js 14.14+ and 16.0+.
200+
They also works in Deno and modern browsers.
201+
181202
## Ports
182203

183204
Franc has been ported to several other programming languages.
@@ -203,14 +224,21 @@ Their creators granted me the rights to distribute franc under the MIT license:
203224
respectively, [Kent S. Johnson][grant-3], [Jacob R. Rideout][grant-2], and
204225
[Maciej Ceglowski][grant-1].
205226

227+
## Contribute
228+
229+
Yes please!
230+
See [How to Contribute to Open Source][contribute].
231+
232+
## Security
233+
234+
This package is safe.
235+
206236
## License
207237

208238
[MIT][] © [Titus Wormer][home]
209239

210240
<!-- Definitions -->
211241

212-
[releases]: https://github.com/wooorm/franc/releases
213-
214242
[logo]: https://raw.githubusercontent.com/wooorm/franc/a162cc0/logo.svg?sanitize=true
215243

216244
[build-badge]: https://github.com/wooorm/franc/workflows/main/badge.svg
@@ -235,6 +263,14 @@ respectively, [Kent S. Johnson][grant-3], [Jacob R. Rideout][grant-2], and
235263

236264
[grant-3]: https://github.com/wooorm/franc/issues/6#issuecomment-59936827
237265

266+
[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
267+
268+
[esmsh]: https://esm.sh
269+
270+
[typescript]: https://www.typescriptlang.org
271+
272+
[contribute]: https://opensource.guide/how-to-contribute/
273+
238274
[mit]: license
239275

240276
[home]: http://wooorm.com

0 commit comments

Comments
 (0)