Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/oguimbal/smartloc

A i18n toolset for nodejs apis leveraging tagged strings
https://github.com/oguimbal/smartloc

apollo-server expressjs graphql hacktoberfest i18n translation typescript

Last synced: 6 months ago
JSON representation

A i18n toolset for nodejs apis leveraging tagged strings

Awesome Lists containing this project

README 

          
# Purpose



If like me:

- you are developping a NodeJS API server which requires internationalization.

- you find most i18n libraries too complicated for your needs, or requiring a refactoring of your existing architecture

- you find it painful to propagate the request accepted languages in all your application parts



... then this library might be for you.



Read a tutorial to learn how to use this lib [here](https://dev.to/oguimbal/i18n-express-apollo-graphql-server-translation-made-simple-33f5)



# Framework support



There are almost-one-liners integrations with the following frameworks:



- [Express](https://github.com/apollographql/apollo-server/tree/master/packages/apollo-server-express) => see [this sample](./samples/express/main.ts)

- [Apollo server express](https://github.com/apollographql/apollo-server/tree/master/packages/apollo-server-express) => see [this sample](./samples/graphql/main.ts)



# How this works



Install it



```bash

npm install smartloc --save

```



Just forget manipulating already translated strings in your code. It is cumbersome, and might leak languages you dont understand in your logs.



Smartloc allows you to declare in your code strings like that:



```typescript

// recommanded: Explicitely specify a string unique ID

const myString = loc('stringUniqueId')`Hello ${name}, how are you today ?`;



// If you are not affraid of occasionally losing some translations when changing your code,

// then you can use this simpler form:

const myString = loc`Hello ${name}, how are you today ?`;

// => An ID will be autogenerated based on this string hash

//   => you might lose translations when changing the original string in code.

```



Those will give you an instance of `StrLoc` interface.



Here is how you can use it:

```typescript

// build a translatable string

const name = 'world';

const str = loc`Hello ${name}`; // nb: This one will have an auto-generated id.



// Just fake loading translations

setDefaultLocale('en');

addLocale('fr', {

    [str.id]: 'Bonjour {0}',

});



// Use the string without language context (logs, ...)

console.log(str.toString()); // => Hello world

console.log(JSON.stringify({msg: str})); // => {"msg": "Hello world"}



// ... or with language context (when returning a query result, ...)

console.log(withLocales(['it', 'fr'], () => str.toString())); // => Bonjour world

console.log(withLocales(['it', 'fr'], () => JSON.stringify({msg: str})); // => {"msg": "Bonjour world"}

```



As you might see, the translation is NOT performed when you build the string, but when you actually try to send a result to your end user.



This allows you to build your app without caring about knowing which language your user accepts.

The translation will be automatically performed when sending actual json to your user, through a simple middleware (see samples listed in "Framework Support")



# Translating your app



## Generating/updating translations from code

As an example, if you write your code in english, and you would like to translate your app in French and Deutsch, add the following script to your package.json file:



```typescript

{

    "scripts": {

        "smartloc": "smartloc collect --format=json --locales=fr-FR,de-DE --defaultLocale=en-US"

    }

}

```



Once you have written your code (or each time you have changed it), you can run `npm run smartloc` to create/update your translation files.



nb: The `--defaultLocale` argument is optional, and will be infered from your code if you explicitly call `setDefaultLocale()` somewhere.



## Loading available translations on server boot



Before serving any request, you must:

1) Tell smartloc which is the default locale (the one you wrote your translations in)

2) Load other locales



For 1), this is straightforward: `setDefaultLocale('en-US')`



To load other locales, you have several options:



### Option 1 - Define in code:

```typescript

import {addLocale} from 'smartloc';



// you could also pass here an object loaded from your database, or whatever

addLocale('fr-FR', {

    mySentenceId: 'Une traduite en français',

});

```



### Option 2 - Load a single given file



```typescript

import { loadAllLocales } from 'smartloc/node';



await loadAllLocales('/path/to/my-translation.json', true);

```



nb: The second argument is 'merge'... if false, all previously loaded translations will be cleared. Else, translations will be merged.



### Option 3 - Scan a directory for translations



```typescript

import { loadAllLocales } from 'smartloc/node';



await loadAllLocales('/path/to/dir/to/scan', true);

```



nb: The second argument is 'merge'... if false, all previously loaded translations will be cleared. Else, translations will be merged.



## Supported formats



Smartloc cli implements two translation format through the `--format` argument



- `--format=json` : JSON translation files

- `--format=xliff` : XLIFF translation files



nb: Smartloc is grouping your translation IDs by category, detected by the first "." in your ID.



# Other use cases



The `LocStr` interface has [several implementations](./src/core/smartloc.ts):



### Smartloc

The default one which is returned when using the `loc` tag:

```typescript

return loc`Hello`;

```



### MultiLoc

If you wish to declare all translations directly in your code:

```typescript

return new MultiLoc({

    en: 'Hello',

    fr: 'Bonjour',

});

```



### SingleLoc

If you wish to declare a string that is the same in all languages, but which is typed as a `LocStr`:

```typescript

return new SingleLoc('Typescript');

```



### TransformedLoc

Sometimes, you will want to apply transformations to your final string.

You can do that using the `.transform()` method available on `LocStr`, which will return you a transformed translatable string.



```typescript

return loc`Some string wich can contain html`

        .transform(x => escapeHtml(x)); // apply a transformation

```



## Array of LocStr

When you have an array of smartloc strings that you want to join, you can use the `LocStringArray` class:



```typescript

const array = new LocStringArray([loc`Hello`, loc`world`]);



const str = array.join(' ').transform(x => x + ' !');



console.log(str.toString('en')); // => Hello world !

console.log(str.toString('fr')); // => Bonjour monde !

```



## Serialization in an untranslated form



Somtimes, you will want to serialize an arbitrary `LocStr` in its untranslated form (to store a localizable sentence in a DB, for instance).



In this case, you can serialize it like that:



```typescript

import {loc, MultiLoc, withSerializationContext} from 'smartloc';

const sampleObject = {

    reference: loc('stringId')`Hello {world}`,

    multi: new MultiLoc({ en: 'A string', fr: 'Une chaine' }),

};



// serialize

const serialized = withSerializationContext(() => JSON.stringify(sampleObject));



// store ... nb: it will look like {"reference": "i18n/id:stringId", "multi": {"i18n:fr": "A string", "i18n:en": "Une chaine"}}

storeInDb(serialized);

```



You can deserialize it back to translatable instance later like that:



```typescript

import {toLocalizable} from 'smartloc';

const obj = loadFromDb();



// get back a translatable intance

const serializable = toLocalizable(obj);

```



## Cloning

Beware, if you deep-clone an object containing smartloc string instances, you must:

- Clone the object prototype

- Clone symbol properties



... or you could just ignore cloning smartloc strings altogether (they are immutable anyway): You can detect them using the `isLocStr()` method and skip them when performing your deep clone.



NB: Of course, if you clone your object using `JSON.parse(JSON.stringify(obj))`, then you will lose translatability (smartloc strings will be translated as strings in your default language).