{"id":19777438,"url":"https://github.com/ilib-js/ilib-yaml","last_synced_at":"2025-04-30T19:32:23.129Z","repository":{"id":239673295,"uuid":"798964840","full_name":"iLib-js/ilib-yaml","owner":"iLib-js","description":"Library to turn yaml files into Resources and vice-versa","archived":true,"fork":false,"pushed_at":"2024-11-12T12:59:13.000Z","size":55,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-05T02:24:41.661Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/iLib-js.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":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-10T21:10:22.000Z","updated_at":"2024-11-21T22:04:32.000Z","dependencies_parsed_at":"2024-05-14T00:52:01.925Z","dependency_job_id":"1b205375-de2b-4907-aab5-b153cd9dcbcc","html_url":"https://github.com/iLib-js/ilib-yaml","commit_stats":null,"previous_names":["ilib-js/ilib-yaml"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iLib-js%2Filib-yaml","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iLib-js%2Filib-yaml/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iLib-js%2Filib-yaml/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iLib-js%2Filib-yaml/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iLib-js","download_url":"https://codeload.github.com/iLib-js/ilib-yaml/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251769480,"owners_count":21640911,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":"2024-11-12T05:24:53.796Z","updated_at":"2025-04-30T19:32:23.115Z","avatar_url":"https://github.com/iLib-js.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\u003e :warning: **Deprecation Notice** :warning:\n\u003e This repository has been deprecated. Please use the corresponding package from the [iLib-js monorepo](https://github.com/iLib-js/ilib-mono) instead.\n\n# ilib-yaml\n\nLibrary to turn yaml files into Resources and vice-versa.\n\n# Basic Usage\n\nThis library exports a class YamlFile which reads or writes\nyaml files. You can then add instances of Resource or get\nan array of Resource instances.\n\nHere is the full [API documentation](./docs/ilibYaml.md)\n\nTo read a yaml file and convert it to Resources where the strings\nappear as source strings:\n\n```javascript\nimport Yaml from 'ilib-yaml';\nimport fs from 'node:fs';\n\nconst yaml = new Yaml();\nyaml.deserialize(fs.readFileSync(\"./my/file.yaml\", \"utf-8\"));\n\nconst resources = yaml.getResources();\n```\n\nTo read a yaml file and convert it to Resources where the\nstrings appear as target strings:\n\n```javascript\nimport Yaml from 'ilib-yaml';\n\n// the source strings\nconst src = new Yaml();\n\nsrc.deserialize(fs.readFileSync(\"./my/en-US.yaml\", \"utf-8\"));\n\n// read this as target strings, and get the source\n// strings from the YamlFile we pass in\nconst tgt = new Yaml({\n    sourceYaml: src,\n    locale: \"de-DE\"\n});\ntgt.deserialize(fs.readFileSync(\"./my/de-DE.yaml\", \"utf-8\"));\n\nconst resources = tgt.getResources();\n```\n\nTo convert an array of Resources into a yaml file:\n\n```javascript\nimport Yaml from 'ilib-yaml';\n\nconst y = new Yaml(); // no argument means new, empty instance\n\ny.addResource(resource);\n// or if you have many\ny.addResources(resourceArray);\n\nfs.writeFileSync(y.serialize(), \"utf-8\");\n```\n\nPlease note that all entries in a yaml file are converted into Resource\ninstances. In many yaml files, not every entry is a translatable string,\nso this is possibly not what you want. It is up to the caller to filter\nthe Resource array afterwards to discard any entries that are not needed.\nThis is accomplished by passing in a filter callback function to the\nconstructor, or by discarding the unwanted resources after they are\nretrieved from this instance.\n\n## Filling out the Resource Instances\n\nThe above examples were simplified to show the basic usage, but in most\nusages, Resource instances can contain many fields. In order to get these\nfields filled out, you can specify the values to use in the constructor:\n\n```javascript\nimport Yaml from 'ilib-yaml';\n\n// the source strings\nconst src = new Yaml({\n    pathName: \"./my/en-US.yaml\",\n    locale: \"en-US\"\n});\n\nsrc.deserialize(fs.readFileSync(\"./my/en-US.yaml\", \"utf-8\"));\n\n// read this as target strings, and get the source\n// strings from the YamlFile we pass in\nconst tgt = new Yaml({\n    sourceYaml: src,\n    // this becomes the targetLocale field because we are creating\n    // full source+target resources\n    locale: \"de-DE\",\n    // these optional fields will get added to every Resource\n    // instance if they are specified here in the constructor:\n    pathName: \"./my/de-DE.yaml\",\n    project: \"myproject\",\n    context: \"a\",\n    state: \"new\",\n    datatype: \"yaml\",\n    flavor: \"b\"\n});\ntgt.deserialize(fs.readFileSync(\"./my/de-DE.yaml\", \"utf-8\"));\n\nconst resources = tgt.getResources();\n```\n\nAdditionally, reskey field will be filled in automatically based on the key\nin the yaml file itself. Different levels of keys in a yaml file will be\nconcatenated together with dots to form the reskey name.\n\nExample:\n\n```yaml\na:\n    b:\n        c: this is a string\n```\n\nThe above simple yaml will produce a string resource with the reskey \"a.b.c\"\nand the source string \"this is a string\".\n\nNote that after the yaml file is converted into an array of Resource instances,\nthe caller is welcome to then amend each Resource instance to add any other\nfields as necessary.\n\n## Arrays and Plurals\n\nMost entries in yaml files are converted into ResourceString instances, except\nfor yaml arrays which are converted into ResourceArray instances.\n\nEach i18n library that uses yaml files as a way of representing translations\nhas its own conventions as to how plurals are represented in that yaml file.\nSince there is no generally recognized way of representing plurals in yaml\nfiles, none of the entries in a yaml file will become ResourcePlural\ninstances. Instead, they will be represented as multiple ResourceString\ninstances. It is up to the caller to take one or more ResourceString\ninstances and transform them into a ResourcePlural instance using the\nconventions of that i18n library.\n\nExample where a plural is represented as separate strings under a key\nwhere the key for those strings is a CLDR plural category name:\n\n```yaml\na:\n    b:\n        one: This is the singular string\n        other: This is the plural string\n    d: not a plural string because there are no CLDR plural categories\n```\n\nDeserializing the above yaml file will result in three ResourceString instances\nwith the reskeys \"a.b.one\" and \"a.b.other\" and \"a.d\". A caller can then post-process\nthose ResourceString instances into a single ResourcePlural instance with the\nreskey \"a.b\" and two plural categories \"one\" and \"other\", followed by another\nregular string that was not recognized as a plural because it did not have\nsubkeys that are CLDR plural category names. It is up to the caller to implement\nany conventions to represent plurals based on the type of i18n library that\nis being used to load these translations.\n\n# License\n\nCopyright 2024 JEDLSoft\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\nhttp://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n\n# Release Notes\n\n## 1.0.1\n\n- upgraded dependencies to avoid a dependabot problem\n\n## 1.0.0\n\n- extracted code from the loctool plugin ilib-loctool-yaml and made a separate\n  library out of it so that it can be shared\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Filib-js%2Filib-yaml","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Filib-js%2Filib-yaml","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Filib-js%2Filib-yaml/lists"}