{"_id":"@denandreychuk/nestjs-localization","_rev":"1-3966c8fb05c5389e9f77314ad83c9368","name":"@denandreychuk/nestjs-localization","dist-tags":{"latest":"0.0.6"},"versions":{"0.0.5":{"name":"@denandreychuk/nestjs-localization","version":"0.0.5","description":"The localization package for your NestJS Applications","main":"dist/index.js","types":"dist/index.d.ts","keywords":["nestjs","nestjs-localization","nestjs-language","nestjs-multilingual"],"repository":{"type":"git","url":"git+https://github.com/squareboat/nestjs-localization.git"},"bugs":{"url":"https://github.com/squareboat/nestjs-localization/issues"},"homepage":"https://github.com/squareboat/nestjs-localization","author":{"name":"Rasik Raj","email":"rasikraj01@gmail.com"},"private":false,"license":"MIT","scripts":{"build":"rm -rf dist && tsc -p tsconfig.json","format":"prettier --write \"**/*.ts\"","lint":"eslint 'lib/**/*.ts' --fix","prepublish:npm":"npm run build","publish:npm":"npm publish --access public","prepublish:next":"npm run build","publish:next":"npm publish --access public --tag next","test:e2e":"jest --config ./tests/jest-e2e.json --runInBand","test:e2e:dev":"jest --config ./tests/jest-e2e.json --runInBand --watch"},"devDependencies":{"@nestjs/common":"^9.3.1","@nestjs/core":"^9.2.1","@types/node":"^18.11.18","reflect-metadata":"^0.1.13","typescript":"^4.1.3"},"peerDependencies":{"@nestjs/common":"^6.7.0 || ^7.0.0 || ^8.0.0 || ^9.0.0 || ^10.0.0","@nestjs/core":"^6.7.0 || ^7.0.0 || ^8.0.0 || ^9.0.0 || ^10.0.0"},"_id":"@denandreychuk/nestjs-localization@0.0.5","gitHead":"e6f9d740ddaa78f48e8c91f2a35cfac6bdb3bc04","_nodeVersion":"21.6.2","_npmVersion":"10.2.4","dist":{"integrity":"sha512-PIdIMgYDJxKC0r/gq3i4EU326Jk72q9+HnVWGQNoRKeAGQPefOlhZ0/wzFvQQFyjeeiALWUX6UrShWh9CHPIkQ==","shasum":"5ff65b914fdb3a7f1a7b2a140c0333e885910dc0","tarball":"https://registry.npmjs.org/@denandreychuk/nestjs-localization/-/nestjs-localization-0.0.5.tgz","fileCount":5,"unpackedSize":24129,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIFszOMo5EiWB1kjzAVM8K1QIvCwxfz4+8CwGGTew1lYvAiEAs271jD3Syq0Em0AA9PAGXQjGbw2wSj1ay26OPvED8hM="}]},"_npmUser":{"name":"denandreychuk","email":"denis.andrei4uk@gmail.com"},"directories":{},"maintainers":[{"name":"denandreychuk","email":"denis.andrei4uk@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/nestjs-localization_0.0.5_1709423324132_0.8264452566933767"},"_hasShrinkwrap":false},"0.0.6":{"name":"@denandreychuk/nestjs-localization","version":"0.0.6","description":"The localization package for your NestJS Applications","main":"dist/index.js","types":"dist/index.d.ts","keywords":["nestjs","nestjs-localization","nestjs-language","nestjs-multilingual"],"repository":{"type":"git","url":"git+https://github.com/denandreychuk/nestjs-localization.git"},"bugs":{"url":"https://github.com/denandreychuk/nestjs-localization/issues"},"homepage":"https://github.com/denandreychuk/nestjs-localization","author":{"name":"Rasik Raj","email":"rasikraj01@gmail.com"},"private":false,"license":"MIT","scripts":{"build":"rm -rf dist && tsc -p tsconfig.json","format":"prettier --write \"**/*.ts\"","lint":"eslint 'lib/**/*.ts' --fix","prepublish:npm":"npm run build","publish:npm":"npm publish --access public","prepublish:next":"npm run build","publish:next":"npm publish --access public --tag next","test:e2e":"jest --config ./tests/jest-e2e.json --runInBand","test:e2e:dev":"jest --config ./tests/jest-e2e.json --runInBand --watch"},"devDependencies":{"@nestjs/common":"^9.3.1","@nestjs/core":"^9.2.1","@types/node":"^18.11.18","reflect-metadata":"^0.1.13","typescript":"^4.1.3"},"peerDependencies":{"@nestjs/common":"^6.7.0 || ^7.0.0 || ^8.0.0 || ^9.0.0 || ^10.0.0","@nestjs/core":"^6.7.0 || ^7.0.0 || ^8.0.0 || ^9.0.0 || ^10.0.0"},"_id":"@denandreychuk/nestjs-localization@0.0.6","gitHead":"935923cb35db53397e4c959f48a02648c85be6fc","_nodeVersion":"21.6.2","_npmVersion":"10.2.4","dist":{"integrity":"sha512-iMaO8zWfNN/W8U5xqHwU9xO311FYOY9Zn2uQzggQa/7SUPtG9+PZPdQvSHyb+75wCF6vAlfI7jqdILjxGfJt5Q==","shasum":"d9330c64d3aa1bfbcab226ead3fe1e61c4bc2290","tarball":"https://registry.npmjs.org/@denandreychuk/nestjs-localization/-/nestjs-localization-0.0.6.tgz","fileCount":31,"unpackedSize":43956,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQC+rbtHhepfcQ0EeFcAgL8q9FJHKwiMBRd+p49GrSHCBwIhAI6nYRThYWY1d8OC98W0LT0ilGw7GiVdHaRXxCKn5ss8"}]},"_npmUser":{"name":"denandreychuk","email":"denis.andrei4uk@gmail.com"},"directories":{},"maintainers":[{"name":"denandreychuk","email":"denis.andrei4uk@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/nestjs-localization_0.0.6_1709423770695_0.7366059080153029"},"_hasShrinkwrap":false}},"time":{"created":"2024-03-02T23:48:44.052Z","0.0.5":"2024-03-02T23:48:44.307Z","modified":"2024-03-02T23:56:11.500Z","0.0.6":"2024-03-02T23:56:10.845Z"},"maintainers":[{"name":"denandreychuk","email":"denis.andrei4uk@gmail.com"}],"description":"The localization package for your NestJS Applications","homepage":"https://github.com/denandreychuk/nestjs-localization","keywords":["nestjs","nestjs-localization","nestjs-language","nestjs-multilingual"],"repository":{"type":"git","url":"git+https://github.com/denandreychuk/nestjs-localization.git"},"author":{"name":"Rasik Raj","email":"rasikraj01@gmail.com"},"bugs":{"url":"https://github.com/denandreychuk/nestjs-localization/issues"},"license":"MIT","readme":"# Nestjs Localization\n\nNestjs localization provides a convenient way to retrieve strings in various languages, allowing you to easily support multiple languages within your application.\n\n## Table of Contents\n\n- [Table of Contents](#table-of-contents)\n- [Installation](#installation)\n- [Getting Started](#getting-started)\n  - [Static Import](#static-import)\n  - [Dynamic Import](#dynamic-import)\n- [Defining Translation Strings](#defining-translation-strings)\n- [Retrieving Translation Strings](#retrieving-translation-strings)\n- [Replacing Parameters In Translation Strings](#replacing-parameters-in-translation-strings)\n- [Pluralization](#pluralization)\n- [Contributing](#contributing)\n- [About Us](#about-us)\n- [License](#license)\n\n## Installation\n\nTo install the package, run :\n\n`npm i @squareboat/nestjs-localization`\n\nOr if you are using yarn\n\n`yarn add @squareboat/nestjs-localization`\n\n## Getting Started\n\nLanguage strings may be stored in files within the a directory. Within this directory, the translation strings are to be defined in JSON files.When taking this approach, each language supported by your application would have a corresponding JSON file within this directory. This approach is recommended for application's that have a large number of translatable strings.\n\nWe would recommend you to store the files in `resources/lang` directory. Also, it is recommended to name your language files using the language <a href=\"https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes\">ISO-2</a> codes.You need to pass the absolute path to the directory you decide to store your files in, while registering the module.\n\nRecommended directory structure :\n\n```\n/resources\n    /lang\n        en.json\n        es.json\n/src\npackage.json\n```\n\nOnce you have the `@squareboat/nestjs-localization` package installed in your project. You'll need to import the module into your application. You can import the module statically or dynamically. You also need to specify a fallback language that the package will fall back to if no language is specified or the key for that language is not available.\n\n#### Static Import\n\nTo import the module statically, you can do\n\n```javascript\nimport { Module } from '@nestjs/common';\nimport { LocalizationModule } from '@squareboat/nestjs-localization/dist/src';\n\n@Module({\n  imports: [\n    LocalizationModule.register({\n      path: 'absolute/path/to/your/resource/directory',\n      fallbackLang: 'en',\n    }),\n  ],\n})\nexport class AppModule {}\n```\n\n#### Dynamic Import\n\nTo import the module dynamically, create a configuration and load it into your `Config Module`. Read about it <a href='https://docs.nestjs.com/techniques/configuration#configuration-namespaces'>here.</a>\n\n```javascript\nimport { registerAs } from '@nestjs/config';\n\nexport default registerAs('localization', () => ({\n  path: 'absolute/path/to/your/resource/directory',\n  fallbackLang: 'en',\n}));\n```\n\nNow that the configuration is loaded, you can import your module asynchronously.\n\n```javascript\nimport { Module } from '@nestjs/common';\nimport { LocalizationModule } from '@squareboat/nestjs-localization/dist/src'';\n\n@Module({\n  imports: [\n    LocalizationModule.registerAsync({\n      imports: [ConfigModule],\n      useFactory: (config: ConfigService) => config.get('localization'),\n      inject: [ConfigService],\n    }),\n  ],\n})\nexport class AppModule {}\n```\n\n### Defining Translation Strings\n\nTypically, translation strings are stored in files within the resources/lang directory. Within this directory you'll have JSON files contianing the key value pairs for a particular language.\nFor example, if your application has a English translation, you should create a `resources/lang/en.json` file:\n\n```json\n// en.json\n\n{\n  \"welcome\": \"Welcome to this application\",\n  \"helloWorld\": \"Hello World\"\n}\n```\n\nFor applications with a large number of translatable strings, defining every string with a \"short key\" can become confusing when referencing the keys in your views and it is cumbersome to continually invent keys for every translation string supported by your application.\nFor example, if your application has a German translation, you should create a `resources/lang/de.json` file:\n\n```json\n// de.json\n\n{\n  \"Have a good day\": \"Haben Sie einen guten Tag\"\n}\n```\n\nAlso, you can nest your strings inside the json file.\nExample :\n\n```json\n// en.json\n\n{\n  \"greetings\": {\n    \"morning\": \"Good Morning\",\n    \"evening\": \"Good Evening\"\n  }\n}\n```\n\n> **NOTE** You should not create conflicting keys i.e 2 keys should not have the same name.\n\n### Retrieving Translation Strings\n\nYou may retrieve translation strings from your language files using the `__` helper function. The `__` function takes 2 required arguments, the key of the translation string you wish of retrive and the language code. You can use `.` the dot notation to refer to nested strings.\n\n```javascript\n__(key: string, language?: string, options?: Record<string, any>): string\n```\n\nExamples :\n\n```javascript\n__('helloWorld', 'en'); // returns => Hello Worlds\n__('Have a good day', 'de'); // returns => Haben Sie einen guten Tag\n__('greetings.morning', 'en'); // returns => Good Morning\n__('randomKey', 'en'); // returns => ERR::INVALID KEY ==> randomKey\n```\n\nYou can also skip the language parameter if you wish to and the package will use the fallback language as the speified language.\nExamples :\n\n```javascript\n__('helloWorld'); // returns => Hello World\n__('greetings.morning'); // returns => Good Morning\n__('randomKey'); // returns => ERR::INVALID KEY ==> randomKey\n```\n\n### Replacing Parameters In Translation Strings\n\nIf you wish, you may define placeholders in your translation strings. All placeholders are prefixed with a `:`. For example, you may define a personalized hello message with a placeholder name:\n\n```json\n// en.json\n\n{\n  \"hello\": \"Hello, :name\"\n}\n```\n\nTo replace the placeholders when retrieving a translation string, you may pass an array of replacements as the second argument to the `__` function:\n\n```javascript\n__('hello', 'en', { name: 'jeo' }); // returns => Hello, jeo\n```\n\nIf your placeholder contains all capital letters, or only has its first letter capitalized, the translated value will be capitalized accordingly:\n\n```json\n\"hello\": \"Hello, :Name\"      // Hello, Jeo\n  // OR\n\"hello\": \"Hello, :NAME\"     // Hello, JEO\n```\n\n## Pluralization\n\nPluralization is a complex problem, as different languages have a variety of complex rules for pluralization; however, `@squareboat/nestjs-localization` can help you translate strings differently based on pluralization rules that you define. Using a `|` character, you may distinguish singular and plural forms of a string:\n\n```json\n\"apples\" : \"There is one apples|There are many apples\"\n```\n\nYou may even create more complex pluralization rules which specify translation strings for multiple ranges of values:\n\n```json\n\"apples\": \"[0] There is no apple|[1,10] There are some apples|[11,*] There are many apples\",\n```\n\nAfter defining a translation string that has pluralization options, you may use the `transChoice` function to retrieve the line for a given \"count\".\n\n```javascript\ntransChoice(\n  key: string,\n  language?: string | number,\n  count?: number | Record<string, any>,\n  options?: Record<string, any>,\n): string\n```\n\nIn this example, since the count is greater than one, the plural form of the translation string is returned:\n\n```javascript\ntransChoice('apples', 'en', 10); // returns => There are some apples\n```\n\nIf you want the string to use the fallback language you can omit the 2nd parameter as shown below :\n\n```javascript\ntransChoice('apples', 10); // returns => There are some apples\n```\n\n> NOTE : **The count agrument is required for tranChoice**\n\nYou may also define placeholder attributes in pluralization strings. These placeholders may be replaced by passing an array as the third argument to the `transChoice` function:\n\n```json\n// en.json\n\n{\n  \"time\": {\n    \"minutes_ago\": \"[1] :value minute ago|[2,*] :value minutes ago\"\n  }\n}\n```\n\n```javascript\ntransChoice('time.minutes_ago', 'en', 5, { value: 5 }); // returns => 5 minutes ago\n```\n\nIf you would like to display the integer value that was passed to the `transChoice` function, you may use the built-in `:count` placeholder:\n\n```json\n// en.json\n\n{\n  \"apples\": \"[0] There are none|[1] There is one|[2,*] There are :count apples\"\n}\n```\n\n```javascript\ntransChoice('apples', 'en', 30); // returns => There are 30 apples\n```\n\n## Contributing\n\nTo know about contributing to this package, read the guidelines [here](./CONTRIBUTING.md)\n\n## About Us\n\nWe are a bunch of dreamers, designers, and futurists. We are high on collaboration, low on ego, and take our happy hours seriously. We'd love to hear more about your product. Let's talk and turn your great ideas into something even greater! We have something in store for everyone. [☎️ 📧 Connect with us!](https://squareboat.com/contact)\n\n## License\n\nThe MIT License. Please see License File for more information. Copyright © 2020 SquareBoat.\n\nMade with ❤️ by [Squareboat](https://squareboat.com)\n","readmeFilename":"README.npm.md"}