https://github.com/runtimerascal/lingualizer
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
https://github.com/runtimerascal/lingualizer
cli locale localization translation
Last synced: about 2 months ago
JSON representation
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
- Host: GitHub
- URL: https://github.com/runtimerascal/lingualizer
- Owner: RuntimeRascal
- License: mit
- Created: 2019-01-15T01:28:06.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2019-04-03T22:35:12.000Z (about 7 years ago)
- Last Synced: 2025-03-18T22:48:24.789Z (over 1 year ago)
- Topics: cli, locale, localization, translation
- Language: TypeScript
- Homepage:
- Size: 198 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Lingualizer
*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*
*Github* repo: [lingualizer](https://github.com/simpert/lingualizer)
*Github* issues: [lingualizer](https://github.com/simpert/lingualizer/issues)
This project is developed for handling all translations from within several different project types.
One requirement is that it works in a vanilla web environment as well in a `Node Webkit` application and finally within an `Electron` application.
The different project types handle paths and such differently and so we have tried to accomodate each project type.
Within an `Electron` application we wanted the module to be importable from both the **main** proccess and the **renderer** process.
## Installation
*to install just run*
> `yarn add lingualizer`
> or
> `npm i lingualizer --save`
> or
> `bower install lingualizer --save`
to install globally as well so can call cli without specifying node dir .bin cmd
> `yarn global add lingualizer ; yarn add lingualizer`
> or
> `npm -g i lingualizer --save ; npm i lingualizer --save`
## Test
*to run the tests just run*
> `yarn run test`
> or
> `npm run test`
The tests are like smoke tests and perfrom I/O.
They will create directory and test file struture before test that need them and cleanup/ delete created resources on test finish.
So if you plan to run the tests please observe the code.
> Not all the tests do io.
# Getting started
*a very simple javascript based api to get translated strings from localization files*
The module can be accessed through `Lingualizer` so just import the modules and call into the class.
> the modules is written in `typescript` and includes all definitions so discovering members of the `Lingualizer` class should be pretty easy.
``` javascript
/* import the module */
import {Lingualizer} from 'lingualizer';
/* set the locale */
Lingualizer.setLocale( 'es-MX' );
/* [Optional] set the project root directory */
Lingualizer.setProjectDir( process.cwd() );
/* 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 */
let okBtnText = Lingualizer.get( 'okBtn' );
```
There is a `localeChanged` event that you may subscribe to in order to get notified when the locale changes.
``` javascript
function onLocalChanged( lingualizer, args )
{
/* get the localized string again and use it */
let okBtnText = lingualizer.get( 'okBtn' );
}
Lingualizer.localeChanged.subscribe( onLocalChanged );
```
you can organize your translations by category or page or whatever by createing nested keys and getting then as so:
``` javascript
var optionsTitle = Lingualizer.get( 'options.title' );
```
for `Electron` you can use the `remote` in order to essentially use same module in both main and renderer processess
``` javascript
/* from main process import and setup like normal */
import {Lingualizer} from 'lingualizer';
Lingualizer.setLocale( 'es-MX' ); // access like this
/* from renderer process import using electron remote */
const loc = remote.require( 'lingualizer' ).Lingualizer;
let okBtnText = loc.get( 'okBtn' ); // access like this
```
### Logging
the `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.
the `setLogger` accepts a object containg any or none of the following:
```
interface ILogger
{
error?( ...params: any[] ): void;
warn?( ...params: any[] ): void;
info?( ...params: any[] ): void;
verbose?( ...params: any[] ): void;
debug?( ...params: any[] ): void;
log?( ...params: any[] ): void;
}
```
but really only `info` and `error` will be used right now.
# Configuration
> Lingualizer support common rc config pattern and config in *package.json* as per `yargs` module.
create a `.lingualizerrc` or `.lingualizerrc.json` file in your project
``` json
{
"defaultLocale": "en-US",
"defaultTranslationFileName": "%project%", /*project means look up the project directory name and use that*/
"defaulLocalizationDirName": "localization",
"defaultTranslationFileExt": "json",
"cwd": "./common", /* runtime cwd, this will be joined using path.join to the current cwd. its to allow choosing a different directory path */
"cmdCwd" : "", /*like cwd but the path will be used only in cli. lets have a different stucture while developing then runtime*/
"isElectron" : false
}
```
create a `lingualizer` node in the `package.json` configuration
``` json
"lingualizer":
{
"defaultLocale": "en-US",
"defaultTranslationFileName": "%project%", /*project means look up the project directory name and use that*/
"defaulLocalizationDirName": "localization",
"defaultTranslationFileExt": "json",
"cwd": "./common", /* runtime cwd, this will be joined using path.join to the current cwd. its to allow choosing a different directory path */
"cmdCwd" : "", /*like cwd but the path will be used only in cli. lets have a different stucture while developing then runtime*/
"isElectron" : false
},
```
settings in the configuration are loaded right away and can be accessed through the `Lingualizer` class
``` javascript
var defLocale = Lingualizer.DefaultLocale; // get the defaut locale
```
# lingualizer CLI
Once the module has been installed just call into the `cli` tool to set things up in project or to modify translations
> 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.
## create
> 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.
| parameter | description |
| --------------------- | --------------------------------------------------------------------------------- |
| `--locale` or `-l` | choose the culture to create translation file for |
| `--based-off` or `-b` | specify a url of a `json` file to download and set contents of newly created file |
| `--force` | if the file allready exists then overwrite it |
### Examples
---
``` javascript
// will create localization directory if needed and default local with default contents
// the file name will not have locale in name as default locale is used
// the file name will be in format '.json'
create
// the file name will not have 'es-MX' in name if default locale is same */
// the file name will be in format '.es-MX.json' */
// will create localization directory if needed and locale es-MX with default contents */
create --locale es-MX
// will create localization directory if needed and default locale file with contents from url */
// the file name will not have locale in name as default locale is used */
// the file name will be in format '.json' */
create --based-off "https://raw.githubusercontent.com/simpert/lingualizer/master/test/data.json"
// will create localization directory if needed and default local with default contents */
// if the file allready existed then it will be overwritten */
// the file name will be in format '.json' */
create --force
```
## set
> use the `set` command to create new key value pairs in a translation file and to update allready existing values
| parameter | description |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--key` or `-k` or *first* | the key to set tag the trasnalted text |
| `--value` or `-val` or `v` or *second* | the translated text to assign to the `key` |
| `--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 |
### Examples
---
``` javascript
// explicit
set --key --value --locale es-MX
set -k -v -l es-MX
// implicit and assume default culture
set into "hello"
// implicit specify locale
set into "hello" -l es-MX
```
## get
> use to get the **value** of a **key** from either the default `locale` if non provided or a certain locale.
**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**
### Examples
``` javascript
// get all translations from default locale
get
// get all translations from 'es-MX'
get --locale es-MX
// get translation named 'ok' from default locale
get ok
// get translation named 'ok' from 'es-MX' locale
get ok es-MX
// get translation named 'ok' from 'es-MX' locale
get ok --locale es-MX
// get translation named 'ok' from 'es-MX' locale
get --key ok --locale es-MX
```
### Help
```
lingualizer --help
lingualizer create --help
lingualizer get --help
lingualizer set --help
```
```