nolangs

nolangs is a CLI and JS library to automatically generate i18n translation files (i18next compatible) using OpenAI or OpenRouter LLMs. It preserves placeholders, supports incremental translation, Markdown, and is ready for modern frameworks.

Compatibility

The JSON files generated by nolangs are fully compatible with:

• i18next (Node.js, browser, React, Vue, Angular, Svelte, etc.)
• Next.js (via next-i18next or custom loaders)
• React (with react-i18next or any i18n loader)
• Vue (vue-i18n)
• Angular (ngx-translate, i18next)
• Svelte (svelte-i18n, i18next)
• Remix (remix-i18next)
• Astro (astro-i18next, custom loaders)
• Express (i18next-express-middleware)
• NestJS (nestjs-i18n, i18next)
• Any other framework or backend that supports flat or nested JSON for translations

How to use:

• Simply point your i18n library to the generated JSON files in your locales/ directory.
• The structure is compatible with both flat and nested key access.
• Placeholders like {name} are preserved and work with all major i18n libraries.

See below for quick start examples with i18next and other frameworks.

New: Now supports full alignment: you can automatically remove extra keys from target translation files that are not present in the source (English) file, ensuring strict key mirroring across all languages.

Features

• Generates flat JSON files compatible with i18next, React, Next.js, Vue, etc.
• Supports both OpenAI and OpenRouter as LLM providers
• Preserves placeholders like {name}
• Does not overwrite existing translations (unless you choose full alignment)

• Full alignment: If your target translation files contain keys that are not present in the source (English) file, nolangs will detect this and prompt you interactively. You can choose to align all files, removing any extra keys and ensuring all languages have exactly the same keys as the source. This is useful for keeping translations clean and avoiding obsolete or unused keys.

• Supports Markdown in values
• CLI and programmatic usage

Installation

npm install nolangs

How it works

1. You provide a source JSON (e.g. en.json) with your English strings.
2. You configure target languages and your LLM provider (OpenAI or OpenRouter).
3. Run the CLI or use the JS API: the tool generates (or updates) translation files for each language, only translating missing keys. If extra keys are found in any target file, you will be prompted to align and remove them for a perfect match with the source.
4. The output is ready for i18next or any modern i18n loader.

Configuration

By default, nolangs looks for a file named nolangs.config.json in your project root. You can use a different name/location by passing the --config flag to the CLI or the configPath option in JS/TS.

If you do not specify inputFile in your config, nolangs will try to auto-detect a source file (like en.json or <sourceLanguage>.json in ./locales or the project root). If no file is found, the build will stop and show a clear message: you must specify inputFile in your config or add a file like en.json.

Example config file (nolangs.config.json):

{
  "sourceLanguage": "en",
  "targetLanguages": ["fr", "es", "de", "it"],
  "inputFile": "./locales/en.json",
  "outputDir": "./locales",
  "provider": "openai",
  "openai": {
    "apiKey": "YOUR_OPENAI_API_KEY",
    "model": "gpt-3.5-turbo"
  },
  "openrouter": {
    "apiKey": "YOUR_OPENROUTER_API_KEY",
    "model": "openrouter-model-name"
  }
}

• provider: choose between openai (default) or openrouter.

CLI Usage

npx nolangs build

Options:

• --dry-run   Show translations in the console without writing files
• --config <path>   Use a custom config file (default: nolangs.config.json)

Full alignment prompt:

If you run:

npx nolangs build

and any of your target translation files (e.g. fr.json, es.json, etc.) contain keys that are not present in your source file (e.g. en.json), you will see a prompt like this:

Some target files have extra keys not present in English. Do you want to align and remove them? (y/N):

If you answer y, all extra keys will be removed and the target files will be strictly aligned to the source. If you answer n or just press Enter, the files will not be changed except for updating/adding the keys present in the source.

Why align?

This feature is useful to keep your translation files clean and consistent, especially when keys are removed or renamed in the source language. No more obsolete or orphaned keys in your translations!

JS/TS Usage

import { buildTranslations } from 'nolangs';

// Use default config file
await buildTranslations({ dryRun: false });

// Or specify a custom config file
await buildTranslations({ dryRun: false, configPath: './myconfig.json' });

// Force full alignment (remove extra keys in all target files)
await buildTranslations({ dryRun: false, align: true });

Quick start with i18next

The generated files are ready to use with i18next (or similar libraries) out of the box:

import i18next from 'i18next';

i18next.init({
  lng: 'en',
  resources: {
    en: { translation: require('./locales/en.json') },
    it: { translation: require('./locales/it.json') },
    fr: { translation: require('./locales/fr.json') },
    // ...
  }
});

Or, if you use the i18next filesystem backend (Node.js):

import Backend from 'i18next-fs-backend';
i18next.use(Backend).init({
  lng: 'en',
  fallbackLng: 'en',
  backend: {
    loadPath: './locales/{{lng}}.json'
  }
});

License

MIT

Contributing

Pull requests and issues are welcome! For major changes, please open an issue first to discuss what you would like to change.