{"id":26964442,"url":"https://github.com/nicklayb/ts-easy-i18n","last_synced_at":"2025-06-24T04:07:25.546Z","repository":{"id":57380675,"uuid":"120347680","full_name":"nicklayb/ts-easy-i18n","owner":"nicklayb","description":"TypeScript implementation of easy-i18n package. Based on react-easy-i18n","archived":false,"fork":false,"pushed_at":"2020-07-16T06:54:50.000Z","size":120,"stargazers_count":0,"open_issues_count":3,"forks_count":2,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-06-12T07:09:57.542Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/nicklayb.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":"2018-02-05T18:58:09.000Z","updated_at":"2019-09-26T00:47:50.000Z","dependencies_parsed_at":"2022-08-27T16:00:38.833Z","dependency_job_id":null,"html_url":"https://github.com/nicklayb/ts-easy-i18n","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nicklayb/ts-easy-i18n","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicklayb%2Fts-easy-i18n","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicklayb%2Fts-easy-i18n/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicklayb%2Fts-easy-i18n/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicklayb%2Fts-easy-i18n/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nicklayb","download_url":"https://codeload.github.com/nicklayb/ts-easy-i18n/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicklayb%2Fts-easy-i18n/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261601514,"owners_count":23183095,"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":"2025-04-03T06:31:30.872Z","updated_at":"2025-06-24T04:07:25.520Z","avatar_url":"https://github.com/nicklayb.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ts-easy-i18n\n\n## Installation\n\n```ts\nnpm install --save ts-easy-i18n\n```\n\n\n### Usage\n\n#### Creating new language bundle\n\nYou can create a language bundle by using the `registerLang` function from the package. You first pass in the language abbreviation, then you pass the translation object :\n```ts\nimport { registerLang } from 'ts-easy-i18n';\n\nregisterLang('en', {\n    home: 'Home',\n    user: 'User'\n});\n```\n\n##### Nesting language bundles\n\nYou can nest language bundle into sub object for easier listing.\n```ts\nimport { registerLang } from 'ts-easy-i18n';\n\nregisterLang('en', {\n    home: 'Home',\n    user: {\n        firstname: 'Firstname',\n        config: {\n            language: 'Language'\n        }\n    }\n});\n```\n\nAnd then pass in a slug splitted by dot to the `trans()` or `process()` function like :\n\n```ts\nimport { process } from 'ts-easy-i18n';\nprocess('user.config.language') //  Would output \"Language\"\n```\n\n#### Switching locales\n\nYou can switch locale with the `setCurrentLocale` function. **Make sure you already registered the language or it'll fallback to english**\n\n```ts\nimport { registerLang, setCurrentLocale } from 'ts-easy-i18n';\n\nregisterLang('en', {\n    home: 'Home',\n    user: 'User'\n});\n\nsetCurrentLocale('en');\n```\n\n### Advanced usage\n\n#### Parameters\n\nYou may require to parameterize string instead of concatenate them. You can do so by providing your parameter key with a colon (`:`) inside you string. For instance, I want to say Hi to my users.\n\n```ts\nimport { registerLang, process } from 'ts-easy-i18n';\n\nregisterLang('en', {\n    welcome: 'Hi :fullname'\n});\n\nprocess('welcome', {\n    fullname: 'John Doe'\n});\n```\n\nThe rendered text will be `Hi John Doe`.\n\n#### Formatters\n\nYou may want to format text sometimes. It helps you keep your translation base clean and reusable because you will be formatting it on runtime.\n\nFirst, you must register your formatter with the `registerFormatters` helper. It simply takes and object in parameter with the function you use as formatters\n\n```ts\nimport { registerFormatters } from 'ts-easy-i18n';\n\nregisterFormatters({\n    uppercase: text =\u003e text.toUpperCase(),                          //  Uppercases the text\n    surround: (text, params) =\u003e `${params[0]}${text}${params[1]}`,  //  Surround text with whatever\n});\n```\n\nAnd then you pass a string with all the formatters you want splitted by pipes\n\n```ts\nimport { format, process } from 'ts-easy-i18n';\n\nregisterLang('en', {\n    welcome: 'Hi :fullname'\n});\n\nregisterFormatters({\n    uppercase: text =\u003e text.toUpperCase(),\n    exclamation: text =\u003e text + '!',\n});\n\nprocess('welcome', { fullname: 'John Doe' }, ['uppercase', 'exclamation']);\n```\n\nIt would render `HI JOHN DOE!`.\n\n##### Format with parameters\n\nIt may end up with the need to parameterize these formatters. Stay safe, we did it for you. You can, after you formatter key, add a colon (`:`) and pass in parameters splitted by commas\n\nI want a formatter to surround a text with things. Sometimes it'll be parentheses, sometimes brackets.\n\n```ts\nimport { registerFormatters, registerLang, format } from 'ts-easy-i18n';\n\nregisterLang('en', {\n    home: 'Home'\n});\n\nregisterFormatters({\n    surround: (text, params) =\u003e params[0] + text + params[1]\n});\n\nformat('home', ['surround:(,)']);    //  Will output \"(Home)\"\nformat('home', ['surround:[,]']);    //  Will output \"[Home]\"\n```\n\n### Four way to do things\n#### `transChoice` **New**\n##### Declaring cases\n\nThere are two type of pluralisation rule you can use. An `ExactRule` which is exactly a numer or anything. Also a `RangeRule` which checks if a value is between two other value or the Infinity. All you need to do is set an array instead of a string.\n\n**Exact rule**\n\nUse the creator `createExactRule` from the package to proceed.\n\nParameters are :\n- `text`: The text\n- `count` (*optional*): The value to compare (*if you do not provide any value, it's considered as a an \"else\" case where anything will work*)\n\n```ts\n\nimport { createExactRule } from 'ts-easy-i18n';\n\nregisterLang('en', {\n    friends: [\n        createExactRule('No friends... sorry...', 0),   //  If 0 is provided\n        createExactRule('Oh! :count friends, nice'),    //  else (the :count will print the actual given count)\n    ]\n});\n```\n\n**Range rule**\n\nUse the creator `createRangeRule` from the package to proceed.\n\nParameters are :\n- `text`: The text\n- `min`: The minimum value to compare\n- `max` (*optional*): The maximum value to compare (*if you do not provide any value, Infinity will be set*)\n\n```ts\n\nimport { createRangeRule } from 'ts-easy-i18n';\n\nregisterLang('en', {\n    friends: [\n        createRangeRule('You have a friend, that\\'s a strat', 1, 1),    //  You could replace this with an Exact rule\n        createRangeRule('Oh! :count friends, it\\'s a beggining', 2, 5), //  Between 2 and 5\n        createRangeRule('Oh! :count friends, it\\'s a beggining', 6),    //  From 6 and so on\n    ]\n});\n```\n\nHere is how you call it.\n\n```ts\nimport { transChoice } from 'ts-easy-i18n';\n\nregisterLang('fr', {\n    friends: [\n        createExactRule('No friends... sorry...', 0),   //  If 0 is provided\n        createExactRule('Oh! :count friends, nice'),    //  else (the :count will print the actual given count)\n    ],\n    hasFriend: [\n        createExactRule(':fullname has no friend', 0),                  // 0 case\n        createRangeRule(':fullname starts with :count friends', 1, 10), // Between 1 and 10\n        createRangeRule(':fullname has :count friends', 11),            // From 11 and so on\n    ]\n});\n\ntransChoice('friends', 0);  // \"No friends... sorry...\"\ntransChoice('friends', 5);  // \"Oh! 5 friends, nice\"\ntransChoice('hasFriends', 0, { fullname: 'Super Mario' });  // \"Super Mario has no friend\"\ntransChoice('hasFriends', 5, { fullname: 'Super Mario' });  // \"Super Mario starts with 5 friends\"\ntransChoice('hasFriends', 100, { fullname: 'Super Mario' });  // \"Super Mario has 100 friends\"\n```\n\n#### `trans`\nThe trans function only translate the text with parameters. You cannot provide formatters to it.\n\n```ts\nimport { trans } from 'ts-easy-i18n';\n\ntrans('hi');\n//  or\ntrans('hi' , {\n    fullname: 'Paul'\n});\n```\n#### `format`\n\nThe format function only formats the text with given formatters. You cannot translate de text with it.\n\n```ts\nimport { format } from 'ts-easy-i18n';\n\nformat('hi' , ['uppercase']);\n```\n\n#### `process` or `processChoice`\nThe process function does everything from the functions `trans` and `format`. This what to you if you want to format a translated text\n\n```ts\nimport { process } from 'ts-easy-i18n';\n\nprocess('hi');\n//  or\nprocess('hi', { fullname: 'Robert'});\n//  or\nprocess('hi', { fullname: 'Robert'}, ['uppercase']);\n\nprocessChoice('hi', 6, { fullname: 'Robert'}, ['uppercase']);\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnicklayb%2Fts-easy-i18n","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnicklayb%2Fts-easy-i18n","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnicklayb%2Fts-easy-i18n/lists"}