{"id":19860316,"url":"https://github.com/augnustin/i18n-node-yaml","last_synced_at":"2025-05-02T04:30:20.092Z","repository":{"id":57270366,"uuid":"83698004","full_name":"augnustin/i18n-node-yaml","owner":"augnustin","description":"Lightweight translation module for node - YAML support","archived":false,"fork":false,"pushed_at":"2019-08-27T15:54:01.000Z","size":46,"stargazers_count":11,"open_issues_count":0,"forks_count":2,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-20T17:04:01.357Z","etag":null,"topics":["i18n","internationalization","language","npm-package","translation","yaml"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/i18n-node-yaml","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/augnustin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-03-02T16:12:43.000Z","updated_at":"2023-10-20T10:12:14.000Z","dependencies_parsed_at":"2022-09-02T09:51:24.321Z","dependency_job_id":null,"html_url":"https://github.com/augnustin/i18n-node-yaml","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/augnustin%2Fi18n-node-yaml","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/augnustin%2Fi18n-node-yaml/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/augnustin%2Fi18n-node-yaml/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/augnustin%2Fi18n-node-yaml/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/augnustin","download_url":"https://codeload.github.com/augnustin/i18n-node-yaml/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251986606,"owners_count":21675950,"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":["i18n","internationalization","language","npm-package","translation","yaml"],"created_at":"2024-11-12T15:03:56.202Z","updated_at":"2025-05-02T04:30:19.843Z","avatar_url":"https://github.com/augnustin.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![npm version](https://badge.fury.io/js/i18n-node-yaml.svg)](https://badge.fury.io/js/i18n-node-yaml)\n\ni18n-node-yaml\n==============\n\n## Motivations\n\nYet another translation module for node? Not quite.\n\nI created this repo for two main reasons:\n\n### 1. Lack of YAML support in the [main translation module](https://github.com/mashpie/i18n-node)\n\nDespite [having been PRed](https://github.com/mashpie/i18n-node/pull/79) it was never merged, which induces a lack of maintenance.\n\nMost people agree that YAML is a better format for writing translations as content is naturally aligned, and require few special character tweaks.\n\nIt means a non-techie could definitely maintain his own version of a translation file, at very little risks.\n\n### 2. Inverted translation position\n\nGet content organised files:\n\n```\n# translations.yml\n\nhello:\n  world:\n    en: Hello World\n    fr: Bonjour le monde\nfoo:\n  bar: Foo bar\n```\n\nInstead of what all translation module I have ever used do: language organised files:\n\n```\n# en.yml\n\nhello:\n  world: Hello World\nfoo:\n  bar: Foo bar\n```\n\nand\n\n```\n# fr.yml\n\nhello:\n  world: Bonjour le monde\nfoo:\n  bar: Foo bar\n```\n\nI can't find how this structure can be easily maintainable. [I already asked the question on SO](http://stackoverflow.com/questions/25664708/rails-i18n-separate-language-key-at-the-end-of-the-tree), without much success. :s\n\nHaving translated myself several websites, I have always found super efficient to manage **one** file.\n\nHere are the immediate advantages I get:\n- No need to duplicate if word is international/not translatable (eg. `foo.bar`)\n- 1 single file to edit when tree structure moves (and it regularly does)\n- Visually obvious which translations are missing\n- Instant evaluation of the necessity to translate (eg. English `Contact` will do at first then will be translated by `Kontact` in German eventually)\n- Super easy to translate : the original source is only 1 line above! No need fancy software to do that.\n- Files are organized by content, not translations\n\nI'd be curious to hear some cons on this, but I hardly can see any!\n\n## Install\n\nNothing fancy:\n\n```\nnpm install i18n-node-yaml --save\n```\n\n## Usage\n\n### Quick start\n\nInspired by [its grand-bother](https://github.com/mashpie/i18n-node), the syntax goes:\n\n```\n// app.js\nconst i18n = require('i18n-node-yaml')({\n  debug: app.get('environment') !== 'production',\n  translationFolder: __dirname + '/translations',\n  locales: ['en_US', 'fr_FR'],\n  defaultLocale: 'en_US',\n  queryParameters: ['lang'],\n});\n\ni18n.ready.catch(err =\u003e {\n  console.error('Failed loading translations', err);\n});\n\napp.use(i18n.middleware);\n```\n\nTranslations become available in the `req`/`res` objects with:\n\n```\n// Any controller\n\nreq.t('translations.hello.world');\n// OR\nres.locals.t('translations.foo.bar');\n```\n\nThe `res.locals.t` syntax makes it accessible in an `ejs`/`pug` view immediately:\n\n```\n// index.pug\nhtml(lang=getLanguage())\n  head\n    meta(property='og:locale', content=getLocale())\n    for language in getLocales().filter(lang =\u003e lang !== getLocale())\n      meta(property='og:locale:alternate', content=language)\n  body\n    p= t('translations.hello.world')\n```\n\n### Set the locale/language\n\nThere are 4 successive ways to set/detect locale in the middleware.\n\n1. **Query parameter**: Querying `/whatever?lang=en`, modifies the locale for the current query, and updates the cookie for the next ones.\n2. **Cookie**: If absent, the middleware looks for the cookie value\n3. **Header**: If absent, it goes for the best match from the `accept-language` header.\n4. **Default locale**: If none of the above matched, then `defaultLocale` is used.\n\nThe `?lang=` query parameter can be changed within the options by updating the `queryParameters` (note that this is an array, multiple values can be accepted).\n\n### API:\n\n- `getLocale()`: returns the current locale. Eg. `'en_US'`\n- `getLanguage()`: returns the current langage. Eg. `'en'`\n- `getLocales()`: returns an array of available locales: Eg. `['en_US', 'fr_FR']`\n- `getLanguages()`: returns an array of available languages: Eg. `['en', 'fr']`\n- `t(root, path, data, locale)`:\n\n  - **`root` (type: `Object`, optional)** : is the object to get translations from. It is optional as by default its value is the whole translations tree. But it can be useful in the case of an array of values:\n\n    ```\n    # elements.yml\n\n    list:\n      - key: foo\n        value:\n          en: I am crazy\n          fr: Je suis fou\n      - key: bar\n        value:\n          en: I like bars\n          fr: J'aime les bars\n      - key: baz\n        value:\n          en: I'm downstairs\n          fr: Je suis en baz\n    ```\n\n    ```\n    //- index.pug\n    each element in t('elements.list')\n      p(data-key=t(element, 'key'))= t(element, 'value')\n    ```\n\n  - **`path` (type: `string`, required)** : is the dot-separated succession of keys to access the value from the root. If root is not set, `path` becomes the first argument\n\n    You can write, back to the example above: `t('elements.list.0.value')` but you are more likely to loop over the values of the array\n\n  - **`data` (type: `object`, optional)** : allows to make string interpolation in translations.\n\n    Eg.\n\n    ```\n    # emails.yml\n\n    welcome:\n      en: |\n        Welcome ${name},\n        Click on this [link](${link}) to continue.\n        Best\n      fr: |\n        Bienvenue ${name},\n        Cliquez sur ce [lien](${link}) pour poursuivre.\n        Bien à vous\n    ```\n\n    Then `t('emails.welcome', {name: 'Robert', link: 'http://example.com'})` will work as expected.\n\n  - **`locale` (type: `string`, optional)** : most of the time you will use the selected locale in the middleware, but it is possible to override it: `t('translations.hello.world', {}, 'fr')`.\n\n## TODOs\n\nFeel free to contribute.\n\nThe most urgent topic will probably be:\n\n- deal with pluralization (I haven't had the need until now)\n\n## Licence: MIT\n\nCopyright 2017 Augustin RIEDINGER\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faugnustin%2Fi18n-node-yaml","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faugnustin%2Fi18n-node-yaml","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faugnustin%2Fi18n-node-yaml/lists"}