Registry / database / mongoose-intl

mongoose-intl

JSON →
library3.3.0jsnpmunverified

Mongoose schema plugin for multilingual (i18n) fields, version 3.3.0. This plugin allows you to define string fields that store translations in multiple languages as a subdocument, while presenting them as virtual string properties. It supports Mongoose versions 4, 5, and 6 via peer dependencies. Languages are configured via an option array, with optional default language and fallback behavior. The plugin is lightweight and specific to Mongoose, offering a simple API for reading and writing translations using standard get/set methods. Alternative packages like mongoose-i18n or mongoose-multilingual exist, but mongoose-intl is one of the oldest and most used plugins for this purpose.

database
npm install mongoose-intl
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · MONGOOSE-INTL
M
mongoose-intl
databasejavascriptv3.3.0
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

mongooseIntl (default)
✓ const mongooseIntl = require('mongoose-intl');
✗ const mongooseIntl = require('mongoose-intl').default;
This package uses CommonJS module.exports. No default export available in ESM; use `import mongooseIntl from 'mongoose-intl'` only if using ESM wrapper (may not work).
Plugin usage
✓ const mongoose = require('mongoose'); const mongooseIntl = require('mongoose-intl'); mongoose.plugin(mongooseIntl, { languages: ['en', 'fr'] });
✗ mongoose.plugin('mongoose-intl', { languages: ['en', 'fr'] });
You must pass the imported function, not a string.
TypeScript usage
✓ import * as mongooseIntl from 'mongoose-intl';
✗ import mongooseIntl from 'mongoose-intl';
This package does not ship its own TypeScript definitions; you may need to create your own or check @types/mongoose-intl. The import syntax depends on your TypeScript module resolution; `import * as` is safer for CommonJS modules.

Shows how to install, configure, and use mongoose-intl plugin with multilingual fields, including setting and reading translations.

const mongoose = require('mongoose'); const mongooseIntl = require('mongoose-intl'); const blogSchema = new mongoose.Schema({ title: { type: String, intl: true }, body: { type: String, intl: true } }); blogSchema.plugin(mongooseIntl, { languages: ['en', 'de', 'fr'], defaultLanguage: 'en' }); const BlogPost = mongoose.model('BlogPost', blogSchema); async function run() { await mongoose.connect('mongodb://localhost:27017/test', { useNewUrlParser: true, useUnifiedTopology: true }); // Create a post const post = new BlogPost({ title: 'Hello', 'title.de': 'Hallo', 'title.fr': 'Bonjour' }); await post.save(); // Read default language console.log(post.title); // 'Hello' console.log(post.get('title.de')); // 'Hallo' await mongoose.disconnect(); } run();
Debug
Known issues
breakingIn mongoose-intl before version 3.0.0, languages option format changed from object to array. Old format may silently fail.
fix
Update languages option to an array of strings, e.g., ['en', 'fr'].
affects: <3.0.0
deprecatedMongoose version 4 and 5 are no longer maintained; only mongoose 6 is actively supported by Mongoose team.
fix
Upgrade mongoose to version 6 or later.
affects: >=3.0.0
gotchaThe 'fallback' option when true returns translations based on the order of languages array, not a specific default language. Fields missing in the current language will return first available language in the configured order.
fix
Ensure your languages array is ordered by priority if using fallback=true.
affects: >=2.0.0
gotchaVirtual fields are not included in JSON by default unless toJSON virtuals option is set to true. This may cause missing language data in API responses.
fix
Set schema option: { toJSON: { virtuals: true } } or use post.toObject({ virtuals: true }).
affects: >=1.0.0
gotchaOnly String type fields can have intl: true; using other types will cause errors or be ignored silently.
fix
Ensure fields with intl: true are of type String.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: mongooseIntl is not a function
Importing the module incorrectly (e.g., using destructured import or wrong require).
fix
Use `const mongooseIntl = require('mongoose-intl');` (default export).
Error: Mongoose model instance modified paths that are not allowed: title.en
Attempting to set a subdocument path directly on a field that is not intl-enabled or using the wrong syntax.
fix
Use `model.get/set` with language suffix, e.g., `post.set('title.de', 'value')`. Do not modify the internal object directly.
CastError: Cast to string failed for value "{ en: '...' }" at path "title"
Setting the field to an object without first registering the intl plugin.
fix
Add the plugin to the schema before creating the model: `schema.plugin(mongooseIntl, { languages: ... }).`
Upgrade
Version history
3.3.0latest on npm
Audit
Dependencies
mongooserequiredPeer dependency; requires mongoose version 4, 5, or 6 to function.
Agent activity
9 hits · last 30 days
node
8
Resources
githubhttps://github.com/alexsk/mongoose-intl ↗
packagemongoose-intl ↗
homepagehttps://github.com/alexsk/mongoose-intl#readme ↗
mongoose-intl — npm install mongoose-intl · libregistry