franc-cli: Language Detection CLI

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/franc/index.js from /your/app.js not supported. Instead change the require of index.js in /your/app.js to a dynamic import() which is available in all CommonJS modules.

  cause Attempting to `require()` the `franc` library (or any package depending on it internally) in a CommonJS module after `franc` became ESM-only.
  fix Migrate your project or the specific file to use ES module syntax (`import { franc } from 'franc'`) and ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).

• TypeError: franc.all is not a function

  cause Attempting to call `franc.all()` from the `franc` library after it was renamed to `francAll()` in v6.
  fix Update your import and usage to `import { francAll } from 'franc'` and call `francAll()`.

• command not found: franc-cli

  cause `franc-cli` was not installed globally or is not in your system's PATH.
  fix Install the package globally using `npm install -g franc-cli` or ensure that the directory containing the `franc-cli` executable is included in your system's PATH environment variable.

Warnings

• breaking The `franc` library, on which `franc-cli` is based, transitioned to an ESM-only package in version 6.0.0. Consequently, `franc-cli@8.0.0` and newer are also ESM-only. This means `require()` statements are no longer supported, and Node.js 12+ is required.
  Fix: Migrate your project to use ES modules (`import`/`export` syntax) and ensure you are running Node.js v12 or higher. For programmatic use, install and import from `franc` directly.
• breaking The `franc` library's `franc.all()` method was renamed to `francAll()` in version 6.0.0 for better ESM compatibility and adherence to naming conventions.
  Fix: Update your code to use `francAll()` instead of `franc.all()` when importing the `franc` library.
• gotcha `franc-cli` is a command-line interface tool. It is not designed to be imported directly into JavaScript/TypeScript code as a library. For programmatic language detection, you should install and use the `franc` library package.
  Fix: If you intend to use language detection programmatically, install `franc` (`npm install franc`) and import its functions. If you need to run `franc-cli` from a script, use `child_process.spawn` or similar methods.
• gotcha The version numbers of `franc-cli` do not directly correlate with the `franc` library versions. For example, `franc-cli@8.0.0` is built upon `franc@6.x.x`. Always consult the monorepo's changelog for specific version dependencies and breaking changes affecting the underlying library.
  Fix: Always refer to the official `franc` monorepo's documentation and changelog to understand the specific `franc` library version bundled with a given `franc-cli` release and any associated breaking changes.

Install

• npm install franc-cli npm
• yarn add franc-cli yarn
• pnpm add franc-cli pnpm

Imports

• franc
  wrong:

  import { franc } from 'franc-cli'

  correct:

  import { franc } from 'franc'

  The `franc-cli` package is a command-line tool. For programmatic language detection within JavaScript/TypeScript applications, you should install and import from the `franc` library package. This library is ESM-only since v6.
• francAll
  wrong:

  import { franc.all } from 'franc'

  correct:

  import { francAll } from 'franc'

  This function, from the `franc` library, was renamed from `franc.all` to `francAll` in `franc` v6. It is also ESM-only, requiring a native ES module import.
• CommonJS require
  wrong:

  const franc = require('franc')

  correct:

  N/A

  The `franc` library, which `franc-cli` uses under the hood, became ESM-only in version 6.0.0. Attempting to `require()` it will result in a runtime error (`ERR_REQUIRE_ESM`).

Quickstart

This quickstart demonstrates how to programmatically execute the `franc-cli` command-line tool from a Node.js script using `child_process` and capture its output to detect the language of a given text string.

import { spawn } from 'child_process';

const textToAnalyze = "Alle menslike wesens word vry en gelyk in waardigheid en regte gebore.";

const child = spawn('franc-cli', [textToAnalyze]);

let output = '';
child.stdout.on('data', (data) => {
  output += data.toString();
});

child.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

child.on('close', (code) => {
  if (code === 0) {
    console.log(`Detected language: ${output.trim()}`);
  } else {
    console.error(`franc-cli exited with code ${code}`);
  }
});