naija-nllb-translate

Translate between English and major Nigerian languages using Meta's open-source NLLB-200 model, run locally in Node.js via ONNX Runtime (@huggingface/transformers).

No Hugging Face Space, no Gradio, no per-request network call. The model weights are downloaded once (from the Hugging Face Hub) and cached on disk; every translation after that runs fully in-process, offline.

Supported languages

| Key | Display name | | -------------- | ------------------------------------ | | english | English | | hausa | Hausa | | igbo | Igbo | | yoruba | Yoruba | | fulfulde | Nigerian Fulfulde | | kanuriArabic | Central Kanuri (Arabic script) | | kanuriLatin | Central Kanuri (Latin script) |

Not currently supported by NLLB-200 (and therefore not in this package): Efik, Ibibio, Tiv, Edo/Bini, Nigerian Pidgin, and most other Nigerian languages beyond the list above. These are absent from FLORES-200, the benchmark NLLB-200 is trained/evaluated on — there is currently no general-purpose MT model covering them. (MAFAND-MT has some Pidgin data if you need that specifically; Efik/Ibibio/Tiv are research-stage only, e.g. the IBOM dataset.)

Install

npm install naija-nllb-translate

Requires Node.js >= 18. On first install, onnxruntime-node downloads a native binary — make sure api.nuget.org (or your platform's equivalent) is reachable in your environment, or the postinstall step will fail.

Usage

import { translate, translateFromEnglish } from "naija-nllb-translate";

const yoruba = await translate("Good morning, how are you?", "english", "yoruba");

const hausa = await translateFromEnglish("Thank you very much", "hausa");

The first call downloads and caches the model (~600MB for the default q8 quantized weights) — expect that first call to take a while. Every call after that, in the same process, is fast.

Warming up ahead of time (recommended for servers)

In a long-running server (Node backend, Next.js API route on a persistent runtime, etc.), call warmUp() once at startup so the model is already loaded before your first real request arrives:

import { warmUp } from "naija-nllb-translate";

await warmUp(); // do this once, at process start

Fully offline (no network at runtime, ever)

Pre-download the model folder yourself (e.g. via git lfs clone https://huggingface.co/Xenova/nllb-200-distilled-600M or the huggingface_hub CLI) onto the machine that will run this package, then:

await translate(text, "english", "hausa", {
  localModelPath: "/path/to/models",
  allowRemoteModels: false,
});

Smaller/faster, at a quality cost

await translate(text, "english", "hausa", { dtype: "q4" });

Hosting notes

This runs a ~600MB model in-process, so where you deploy it matters:

• Vercel / Netlify serverless functions: not recommended. Free-tier function bundle size limits (Vercel's default is 250MB unzipped) and execution timeouts (10s on free tiers) don't fit a 600MB model plus cold inference well, and serverless functions don't keep the model warm in memory between invocations — you'd reload it on every cold start.
• A persistent Node process is the right shape — a Next.js API route is fine as the interface, but deploy it somewhere that keeps a long-running container: a small VPS, Render.com (free web service tier), or Fly.io. Call warmUp() once at boot so the model loads a single time and stays in memory for the life of the process.
• Fully local/offline — run it as a local Node service with no hosting at all, which fits well alongside on-device/offline-first tooling.
• Browser-only — @huggingface/transformers also runs client-side via WASM/WebGPU, so a static site could translate entirely in the visitor's browser with no backend, at the cost of a large first-load download and slower inference on typical client hardware.

Limitations to know about

• Translation quality: NLLB-200 is a general-purpose model, not Nigeria-specific. Translations may miss cultural nuance or idiom — don't rely on it for legal, medical, or official documents without review.
• Model size / RAM: the default q8 600M model needs roughly 1-2GB of RAM to run comfortably. Use dtype: "q4" if you're memory-constrained.
• Not affiliated with Meta or Hugging Face — this is an unofficial convenience wrapper around a publicly available model.

License

MIT