{"id":49245324,"url":"https://github.com/flybits/localized-entity","last_synced_at":"2026-04-24T21:11:24.007Z","repository":{"id":271447914,"uuid":"912882563","full_name":"flybits/localized-entity","owner":"flybits","description":"A vanilla JS middleware used to abstract away the bidirectional data-binding of localized object model attributes.","archived":false,"fork":false,"pushed_at":"2025-06-01T01:53:42.000Z","size":87,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-10-01T21:34:27.398Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flybits.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-01-06T15:33:24.000Z","updated_at":"2025-06-01T01:53:07.000Z","dependencies_parsed_at":"2025-01-07T20:36:18.298Z","dependency_job_id":"614eabca-b8cb-4d1c-b543-fc461df333b0","html_url":"https://github.com/flybits/localized-entity","commit_stats":null,"previous_names":["flybits/localized-entity"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/flybits/localized-entity","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flybits%2Flocalized-entity","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flybits%2Flocalized-entity/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flybits%2Flocalized-entity/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flybits%2Flocalized-entity/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flybits","download_url":"https://codeload.github.com/flybits/localized-entity/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flybits%2Flocalized-entity/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32240705,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T13:21:15.438Z","status":"ssl_error","status_checked_at":"2026-04-24T13:21:15.005Z","response_time":64,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-24T21:11:22.924Z","updated_at":"2026-04-24T21:11:23.995Z","avatar_url":"https://github.com/flybits.png","language":"JavaScript","readme":"# localized-entity\n\nA vanilla JS middleware used to abstract away the bidirectional data-binding of localized object model attributes.\n\n[Live Demo](https://localized.flybits.app/examples/example-basic.html)\n\n## Getting Started\n\n1. Import\n\n```shell\n$ npm install localized-entity --save\n```\n\n```javascript\nimport { LocalizedModel } from 'localized-entity';\n```\n\n2. Extend class definition\n\n```javascript\nclass AppObject extends LocalizedModel{\n  constructor(){\n    super();\n    this.attrValue = '';\n  }\n  fromJSON(obj){\n    this.initLocalizedValue('attrValue', obj.localeValues, 'localizedAttr')\n    return this;\n  }\n  toJSON(){\n    return {\n      localeValues: this.inflateLocales({\n        attrValue: 'localizedAttr'\n      })\n    }\n  }\n}\n```\n\n3. Use to simplify read/update\n\n```javascript\nlet appObj = new AppObject().fromJSON(serverJSON);\n// Read the English value of attrValue\nconsole.log(appObj.attrValue);\n// Update the English value\nappObj.attrValue = 'english value update';\n\n// switch locales\nappObj.localize('fr');\n\n// Read the French value of attrValue\nconsole.log(appObj.attrValue);\n// Update the French value\nappObj.attrValue = 'mise à jour de la valeur française';\n```\n\n## Motivation\n\nWhen building UIs that edit entities that have localized attributes view-model logic is often responsible for managing the mapping of CRUD actions to the respective localized version of an entity.  Namely making sure the English, French, or whichever locale specific values are rendered in a form field and edits to that form field will update the respective localized values.\n\nDeferring this responsibility to view-model logic leads to inconsistent and tedious repetition of object model mapping wherever editing UI such as form fields exist in an application.  This approach is error prone and leads to poor maintainability.\n\nWhen designing client side applications, the need for a unified data layer responsible for interacting with APIs and facilitating client side object models is key.  This creates an abstraction layer between the client side application logic and the source system and centralizes object model logic and maintainence.\n\n![Abtraction layers within an application](https://flybits.app/resources/localized-appstructure.png)\n\nThis library aligns with this paradigm and encapsulates the management of localized attribute mapping to simplify the logic on the view-model layer.  Handling localized attribute value mapping and updates behind the scenes, on the actual object model itself, removes the need for application logic to take this into consideration.  That is to say UI views can bind to simple consistent object model attributes without consideration of which locale is selected on the UI page that would typically require logic to update data bindings to localized versions of the object model attributes.\n\n## Basic Usage\n\nAs an example, if the JSON of your entity from the server looked like the below:\n\n```json\n{\n  \"localizations\": {\n    \"en\": {\n      \"header\": \"this is a header\",\n      \"description\": \"this is a description\"\n    },\n    \"fr\": {\n      \"header\": \"il s’agit d’un en-tête\",\n      \"description\": \"il s’agit d’une description\"\n    }\n  }\n}\n```\n\nIn order to simplify object model usage within the lower view-model layers of your application downstream of your data layer, **localized-entity** will allow you to have an object model that resembles:\n\n```json\n{\n  \"header\": \"this is a header\",\n  \"description\": \"this is a description\"\n}\n```\n\nDepending on your selected locale these attributes will represent their localized versions without any additional logic outside of your class definition.  That is to say your views need only bind once directly to `header` or `description`.\n\nWithin your client side data layer simply define your data model as an ES6 class and extend the LocalizedModel class. Then specify which attributes are localized and provide the localized value mappings.\n\n```javascript\n// extend LocalizedModel\nclass AppObject extends LocalizedModel{\n  constructor(){\n    super();\n    this.header = '';\n    this.description = '';\n    \n    // return localized object proxy\n    return this._localizedProxy;\n  }\n  fromJSON(obj){\n    // initialize model attributes based on localized values\n    this.initLocalizedValue('header', obj.localizations);\n    this.initLocalizedValue('description', obj.localizations);\n\n    return this;\n  }\n  toJSON(){\n    // transform back to server JSON object structure\n    return {\n      localizations: this.inflateLocales({\n        header: 'header',\n        description: 'description'\n      })\n    }\n  }\n}\n```\n\nNow you can use this object model definition to produce simple objects for downstream binding. For example,\n\n```javascript\nconst jsonData = {\n  \"localizations\": {\n    \"en\": {\n      \"header\": \"this is a header\",\n      \"description\": \"this is a description\"\n    },\n    \"fr\": {\n      \"header\": \"il s’agit d’un en-tête\",\n      \"description\": \"il s’agit d’une description\"\n    }\n  }\n};\n// parse server JSON object structure\nlet entity = new AppObject().fromJSON(jsonData);\n// now you can 2 way bind your views to `entity.header` and `entity.description`\n\n// once the language is selected\nentity.localize('en');\n// Read the English value \"this is a header\"\nconsole.log(entity.header);\n// Update the English value\nentity.header = 'change the english header';\n\n\n// change the selected language\nentity.localize('fr');\n// Read the French value \"il s’agit d’un en-tête\"\nconsole.log(entity.header);\n// Update the French value\nentity.header = `changer l'en-tête français`;\n\n// transform back to server JSON object structure\nconst serverPayload = entity.toJSON();\n```\n\n## Nested Objects\n\nIf your object model contains a child object with localized attributes simply utilize the `localizeObj` function within your class definition constructor.\n\nTake for example the following JSON structure\n\n```json\n{\n  \"subObject\": {\n    \"localeValues\": {\n      \"en\": {\n        \"attr1\": \"this is a header\",\n        \"attrName2\": \"this is a description\"\n      },\n      \"fr\": {\n        \"attr1\": \"il s’agit d’un en-tête\",\n        \"attrName2\": \"il s’agit d’une description\"\n      }\n    }\n  }\n}\n```\n\nLeverage `LocalizedModel` functions to initialize and transform localized values.\n\n```javascript\nclass AppObject extends LocalizedModel{\n  constructor(){\n    super();\n    // declare your child object as localized\n    this.child = this.localizeObj('child', {\n      attr1: '',\n      attr2: ''\n    });\n    \n    // return localized object proxy\n    return this._localizedProxy;\n  }\n  fromJSON(obj){\n    // initialize model attributes based on localized values\n    this.initLocalizedValue('child.attr1', obj.subObject.localeValues);\n    // normalize incoming `attrName2` attribute key into `attr2` for consistency\n    this.initLocalizedValue('child.attr2', obj.subObject.localeValues, 'attrName2');\n\n    return this;\n  }\n  toJSON(){\n    // transform back to server JSON object structure\n    return {\n      subObject: {\n        localeValues: this.inflateLocales({\n          'child.attr1': 'attr1',\n          'child.attr2': 'attrName2'\n        })\n      }\n    }\n  }\n}\n```\n\n## Object Arrays\n\nIf your object model contains an object array where each object contains localized attributes simply utilize the `localizeArray` function within your class definition constructor.\n\nTake for example the following JSON structure\n\n```json\n{\n  \"subArray\": [\n    {\n      \"localeValues\": {\n        \"en\": {\n          \"attr1\": \"this is a header\",\n          \"attrName2\": \"this is a description\"\n        },\n        \"fr\": {\n          \"attr1\": \"il s’agit d’un en-tête\",\n          \"attrName2\": \"il s’agit d’une description\"\n        }\n      }\n    }\n  ]\n}\n```\n\nLeverage `LocalizedModel` functions to initialize and transform localized values.\n\n```javascript\nclass AppObject extends LocalizedModel{\n  constructor(){\n    super();\n    // declare your child object array as localized\n    this.children = this.localizeArray('children', ['attr1', 'attr2']);\n    \n    // return localized object proxy\n    return this._localizedProxy;\n  }\n  fromJSON(obj){\n    // initialize model attributes based on localized values\n    obj.subArray.forEach((obj, index) =\u003e {\n      this.children.push({\n        attr1: this.initLocalizedArrValue('children', index, 'attr1', obj.localeValues),\n        // normalize incoming `attrName2` attribute key into `attr2` for consistency\n        attr2: this.initLocalizedArrValue('children', index, 'attr2', obj.localeValues, 'attrName2')\n      })\n    })\n\n    return this;\n  }\n  toJSON(){\n    // transform back to server JSON object structure\n    return {\n      subArray: this.children.map((obj, index) =\u003e {\n        return {\n          localeValues: this.inflateLocales({\n            'children.{index}.attr1': 'attr1',\n            'children.{index}.attr2': 'attrName2'\n          }, index)\n        }\n      })\n    }\n  }\n}\n```\n\n## How It Works\n\nSimilar to the underlying implementation of the [Vue.js v3 reactivity system](https://vuejs.org/guide/essentials/reactivity-fundamentals.html#reactive-proxy-vs-original), **localized-entity** leverages the native [JavaScript Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) to observe changes and update encapsulated localized versions of attribute values.\n\n![Localized attribute value proxy structure](https://flybits.app/resources/localized-proxy.png)","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflybits%2Flocalized-entity","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflybits%2Flocalized-entity","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflybits%2Flocalized-entity/lists"}