{"id":15297146,"url":"https://github.com/runtimerascal/lingualizer","last_synced_at":"2026-05-04T02:38:07.638Z","repository":{"id":86648294,"uuid":"165763118","full_name":"RuntimeRascal/lingualizer","owner":"RuntimeRascal","description":"A simple api for getting translated strings based on a locale and a command line tool for createing translation files and managing the translated strings","archived":false,"fork":false,"pushed_at":"2019-04-03T22:35:12.000Z","size":203,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-18T22:48:24.789Z","etag":null,"topics":["cli","locale","localization","translation"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RuntimeRascal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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":"2019-01-15T01:28:06.000Z","updated_at":"2019-06-19T22:41:00.000Z","dependencies_parsed_at":"2023-03-11T11:30:49.484Z","dependency_job_id":null,"html_url":"https://github.com/RuntimeRascal/lingualizer","commit_stats":null,"previous_names":["simpert/lingualizer"],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RuntimeRascal%2Flingualizer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RuntimeRascal%2Flingualizer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RuntimeRascal%2Flingualizer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RuntimeRascal%2Flingualizer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RuntimeRascal","download_url":"https://codeload.github.com/RuntimeRascal/lingualizer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245467614,"owners_count":20620216,"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":["cli","locale","localization","translation"],"created_at":"2024-09-30T19:15:22.531Z","updated_at":"2026-05-04T02:38:07.556Z","avatar_url":"https://github.com/RuntimeRascal.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lingualizer\n*A simple **nodejs** api for getting translated strings based on a locale and a command line tool for createing translation files and managing the translated strings*  \n\n*Github* repo: [lingualizer](https://github.com/simpert/lingualizer)  \n*Github* issues: [lingualizer](https://github.com/simpert/lingualizer/issues)  \n\nThis project is developed for handling all translations from within several different project types.  \n\nOne requirement is that it works in a vanilla web environment as well in a `Node Webkit` application and finally within an `Electron` application.  \n\nThe different project types handle paths and such differently and so we have tried to accomodate each project type.  \n\nWithin an `Electron` application we wanted the module to be importable from both the **main** proccess and the **renderer** process.   \n\n\n## Installation \n*to install just run*   \n\n\u003e `yarn add lingualizer`  \n\u003e or  \n\u003e `npm i lingualizer --save`  \n\u003e or  \n\u003e `bower install lingualizer --save`  \n to install globally as well so can call cli without specifying node dir .bin cmd\n \u003e `yarn global add lingualizer ; yarn add lingualizer`  \n\u003e or  \n\u003e `npm -g i lingualizer --save ; npm i lingualizer --save`  \n\n## Test \n*to run the tests just run*   \n\n\u003e `yarn run test`  \n\u003e or  \n\u003e `npm run test`    \n\nThe tests are like smoke tests and perfrom I/O.\nThey will create directory and test file struture before test that need them and cleanup/ delete created resources on test finish.\n\nSo if you plan to run the tests please observe the code.\n\n\u003e Not all the tests do io.  \n\n# Getting started\n*a very simple javascript based api to get translated strings from localization files*  \n \nThe module can be accessed through `Lingualizer` so just import the modules and call into the class.\n\n\u003e the modules is written in `typescript` and includes all definitions so discovering members of the `Lingualizer` class should be pretty easy.\n\n``` javascript\n/* import the module */\nimport {Lingualizer} from 'lingualizer';\n\n/* set the locale */\nLingualizer.setLocale( 'es-MX' );\n\n/* [Optional] set the project root directory */\nLingualizer.setProjectDir( process.cwd() );\n\n/* get a localized string. will return from current set locale if exists, or from defualt locale if current set locale doesnt exist and if key cannot be found anywhere returns null */\nlet okBtnText = Lingualizer.get( 'okBtn' );\n```\n\nThere is a `localeChanged` event that you may subscribe to in order to get notified when the locale changes.\n\n``` javascript\nfunction onLocalChanged( lingualizer, args )\n{\n    /* get the localized string again and use it */\n    let okBtnText = lingualizer.get( 'okBtn' );\n}\n\nLingualizer.localeChanged.subscribe( onLocalChanged );\n```  \n\nyou can organize your translations by category or page or whatever by createing nested keys and getting then as so:  \n\n``` javascript\n    var optionsTitle = Lingualizer.get( 'options.title' );\n```\n\nfor `Electron` you can use the `remote` in order to essentially use same module in both main and renderer processess\n``` javascript\n/* from main process import and setup like normal */\nimport {Lingualizer} from 'lingualizer';\nLingualizer.setLocale( 'es-MX' ); // access like this\n\n/* from renderer process import using electron remote */\nconst loc = remote.require( 'lingualizer' ).Lingualizer;\nlet okBtnText = loc.get( 'okBtn' ); // access like this\n```  \n\n\n### Logging\nthe `Lingualizer` has a `setLogger` function that you can use to pass it a object that looks like a logger and if set we will call the `info` and `error` functions on it to log messages.  \n\nthe `setLogger` accepts a object containg any or none of the following:  \n```\n    interface ILogger\n    {\n        error?( ...params: any[] ): void;\n        warn?( ...params: any[] ): void;\n        info?( ...params: any[] ): void;\n        verbose?( ...params: any[] ): void;\n        debug?( ...params: any[] ): void;\n        log?( ...params: any[] ): void;\n    }\n``` \n\nbut really only `info` and `error` will be used right now.\n\n\n# Configuration\n\u003e Lingualizer support common rc config pattern and config in *package.json* as per `yargs` module.  \n\ncreate a `.lingualizerrc` or `.lingualizerrc.json` file in your project  \n``` json\n{\n    \"defaultLocale\": \"en-US\",\n        \"defaultTranslationFileName\": \"%project%\", /*project means look up the project directory name and use that*/\n    \"defaulLocalizationDirName\": \"localization\",\n    \"defaultTranslationFileExt\": \"json\",\n    \"cwd\": \"./common\", /* runtime cwd, this will be joined using path.join to the current cwd. its to allow choosing a different directory path */\n    \"cmdCwd\" : \"\", /*like cwd but the path will be used only in cli. lets have a different stucture while developing then runtime*/\n    \"isElectron\" : false\n}\n```  \n\ncreate a `lingualizer` node in the `package.json` configuration\n``` json\n    \"lingualizer\":\n    {\n        \"defaultLocale\": \"en-US\",\n        \"defaultTranslationFileName\": \"%project%\", /*project means look up the project directory name and use that*/\n        \"defaulLocalizationDirName\": \"localization\",\n        \"defaultTranslationFileExt\": \"json\",\n        \"cwd\": \"./common\", /* runtime cwd, this will be joined using path.join to the current cwd. its to allow choosing a different directory path */\n        \"cmdCwd\" : \"\", /*like cwd but the path will be used only in cli. lets have a different stucture while developing then runtime*/\n        \"isElectron\" : false\n    },\n```   \n\nsettings in the configuration are loaded right away and can be accessed through the `Lingualizer` class  \n``` javascript\nvar defLocale = Lingualizer.DefaultLocale; // get the defaut locale\n```  \n\n# lingualizer CLI\nOnce the module has been installed just call into the `cli` tool to set things up in project or to modify translations\n\n\u003e make sure that you are in the project root directory when calling into the cli. this directory will be searched recursively for a folder called `localization` [or defaulLocalizationDirName from config] and will work with files directly in this directory.\n\n## create\n\u003e If you have allready some translation files with ***key*** ***value*** pairs you can create a new translation file and base it off of. Just specify a url to the `json` file with the `--based-off` parameter.  \n\n\n| parameter             | description                                                                       |\n| --------------------- | --------------------------------------------------------------------------------- |\n| `--locale` or `-l`    | choose  the culture to create translation file for                                |\n| `--based-off` or `-b` | specify a url of a `json` file to download and set contents of newly created file |\n| `--force`             | if the file allready exists then overwrite it                                     |\n\n### Examples\n---\n``` javascript\n    // will create localization directory if needed and default local with default contents\n    // the file name will not have locale in name as default locale is used\n    // the file name will be in format '\u003cproject-name\u003e.json'\n    create\n\n    // the file name will not have 'es-MX' in name if default locale is same */\n    // the file name will be in format '\u003cproject-name\u003e.es-MX.json' */\n    // will create localization directory if needed and locale es-MX with default contents */\n    create --locale es-MX\n\n    // will create localization directory if needed and default locale file with contents from url */\n    // the file name will not have locale in name as default locale is used */\n    // the file name will be in format '\u003cproject-name\u003e.json' */\n    create --based-off \"https://raw.githubusercontent.com/simpert/lingualizer/master/test/data.json\"\n\n    // will create localization directory if needed and default local with default contents */\n    // if the file allready existed then it will be overwritten */\n    // the file name will be in format '\u003cproject-name\u003e.json' */\n    create --force\n```\n\n## set\n\u003e use the `set` command to create new key value pairs in a translation file and to update allready existing values  \n\n| parameter                              | description                                                                                                                                      |\n| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `--key` or `-k`  or *first*            | the key to set tag the trasnalted text                                                                                                           |\n| `--value` or `-val` or `v` or *second* | the translated text to assign to the `key`                                                                                                       |\n| `--locale` or `-l`                     | the locale to determine which file to add translation to. this is an *optional* parameter if if not specified the default locale will be assumed |\n\n### Examples\n---\n``` javascript\n    // explicit\n    set --key \u003ckey\u003e --value \u003cvalue\u003e --locale es-MX\n    set -k \u003ckey\u003e -v \u003cvalue\u003e -l es-MX\n   \n    // implicit and assume default culture\n    set into \"hello\"\n\n    // implicit specify locale\n    set into \"hello\" -l es-MX\n```\n\n\n## get\n\u003e use to get the **value** of a **key** from either the default `locale` if non provided or a certain locale.\n\n**The file name as of right now for the `get` command will be searched for using the settings file default filename or if no settings file will use the default of looking up name of the project directory**\n\n### Examples\n``` javascript\n    // get all translations from default locale\n    get\n\n    // get all translations from 'es-MX'\n    get --locale es-MX\n\n    // get translation named 'ok' from default locale\n    get ok\n    \n    // get translation named 'ok' from 'es-MX' locale\n    get ok es-MX\n\n    // get translation named 'ok' from 'es-MX' locale\n    get ok --locale es-MX\n\n    // get translation named 'ok' from 'es-MX' locale\n    get --key ok --locale es-MX\n```\n\n### Help\n```\nlingualizer --help\nlingualizer create --help\nlingualizer get --help\nlingualizer set --help\n```    \n\n```  ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruntimerascal%2Flingualizer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fruntimerascal%2Flingualizer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruntimerascal%2Flingualizer/lists"}