ember-localized-model

ember-localized-model

Handle mutli-lang model fields where your JSON:API returns a dictionary / object with all languages present.

Example:

{
  "id": "1",
  "type": "books",
  "attributes": {
    "name": {
      "de": "Der Name des Windes",
      "en": "The name of the wind"
    }
  }
}

Compatibility

• Ember.js v4.12 or above
• Ember CLI v4.12 or above
• EmberData v4.12 or above
• Node.js v16 or above

Installation

ember install ember-localized-model

Usage

First steps

To use this addon, first you need to import and extend your model from LocalizedModel:

import { LocalizedModel } from "ember-localized-model";

export default class YourModel extends LocalizedModel {}

To serialize the multi-lang field correctly you also need to add a serializer:

import { LocalizedSerializer } from "ember-localized-model";

export default class YourModelSerializer extends LocalizedSerializer {}

Once this is done, you can start adding your localized field via the @localizedAttr decorator:

import { LocalizedModel, localizedAttr } from "ember-localized-model";

export default class YourModel extends LocalizedModel {
  @localizedAttr firstName;
  @localizedAttr lastName;
}

Accessing the fields value

To read the model field you can simply use yourModel.firstName.

The locale the field displays depends on your intl.primaryLocale. You can change your primaryLocale to display the model field in another locale.

If you want to switch locale for only one specific model, you can set yourModel.localizedFieldLocale to the desired locale.

If your locale has a region such as en-US, but you want to disregard the region. Set sanitizeLocale to true in your ember-cli-build.js file:

module.exports = function (defaults) {
  const app = new EmberApp(defaults, {
    "localized-model": {
      sanitizeLocale: true,
    },
    // ...
  });

  // ...
};

If you want to access the raw data as sent by the backend, you can use yourModel.localizedObjects.firstName. This will return the raw data.

For example:

{
  "de": "Johan",
  "en": "John"
}

Known Issues

Creating model records

If you have your model defined with a @localizedAttr field and directly set the field on store.createRecord the setter for the field will not be called and instead of the dictionary with the locale key, the value directly will be assigned to the field.

The serialized model then looks like this:

{
  "type": "your-model",
  "attributes": {
    "name": "your name"
  }
}

instead of

{
  "type": "your-model",
  "attributes": {
    "name": {
      "en": "your name"
    }
  }
}

Solution: Create your record first and then assign the localized field:

const yourModel = this.store.createRecord("yourModel");
yourModel.name = "this is a test";

Contributing

See the Contributing guide for details.

License

This project is licensed under the LGPL-3.0 License.

Changelog

4.0.1 (2024-07-26)

Bug Fixes

• deps: fix ember data dependencies (ffd927e)
• deps: fix ember source peer dependency range (cc27565)

Bug Fixes

• update dependencies (d3a7725)

BREAKING CHANGES

• This addon now requires ember-intl >= v7, ember-source >= v4.12 and ember-data >= v4.12.