Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kevinnovak/linguini
Npm package - A JSON-based translation file manager.
https://github.com/kevinnovak/linguini
international internationalization json json-schema language locale localization localization-tool multi-language multi-lingual multilanguage multilingual translate translation
Last synced: 3 months ago
JSON representation
Npm package - A JSON-based translation file manager.
- Host: GitHub
- URL: https://github.com/kevinnovak/linguini
- Owner: KevinNovak
- License: mit
- Created: 2021-10-05T03:24:49.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2022-01-14T00:31:15.000Z (about 3 years ago)
- Last Synced: 2024-10-04T05:05:04.770Z (4 months ago)
- Topics: international, internationalization, json, json-schema, language, locale, localization, localization-tool, multi-language, multi-lingual, multilanguage, multilingual, translate, translation
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/linguini
- Size: 739 KB
- Stars: 10
- Watchers: 2
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Linguini
[](https://www.npmjs.com/package/linguini)
[](https://www.npmjs.com/package/linguini)
[](https://github.com/KevinNovak/Linguini/stargazers)
[](https://opensource.org/licenses/MIT)
[](https://github.com/KevinNovak/Linguini/pulls)
**Npm package** - A JSON-based translation file manager.
`npm install linguini`
## Table of Contents
- [Example](#example)
- [Initial Setup](#initial-setup)
- [Installation](#installation)
- [Creating a Linguini Object](#creating-a-linguini-object)
- [Type Mappers](#type-mappers)
- [Built-In Type Mappers](#built-in-type-mappers)
- [Custom Type Mappers](#custom-type-mappers)
- [Variables](#variables)
- [References](#references)
- [General References (REF)](#general-references-ref)
- [Common References (COM)](#common-references-com)
## Example
An example language file, `lang.en.json`:
```jsonc
{
"data": {
// This is a language category:
"intro": {
// This is a language item:
"myFavoriteColor": "My favorite color is blue."
}
},
"refs": {}
}
```
We could have additional translations of this file, for example: `lang.fr.json`, `lang.ru.json`, etc:
Using Linguini, we can retrieve the language item from the appropriate file by passing in the location of the item, and the language code to use:
```js
let englishLine = linguini.get('intro.myFavoriteColor', 'en', TypeMappers.String);
console.log(englishLine);
// Outputs: "My favorite color is blue."
let frenchLine = linguini.get('intro.myFavoriteColor', 'fr', TypeMappers.String);
console.log(frenchLine);
// Outputs: "Ma couleur préférée est le bleu."
```
Here `'intro.myFavoriteColor'` is the category and name of the language item, while `'en'` or `'fr'` tells Linguini which language file to pull from: either `lang.en.json` or `lang.fr.json`.
_Side note: If you're wondering what the `TypeMappers.String` is for, see the section below on [Type Mappers](#type-mappers)._
## Initial Setup
### Installation
`npm install linguini`
### Creating a Linguini Object
```js
import { Linguini } from 'linguini';
// The folder path containing the language files.
let folderPath = path.join(__dirname, './data');
// The base name of the language files to use. Note this should not include any file extensions or language codes.
let fileName = 'lang';
let linguini = new Linguini(folderPath, fileName);
```
## Type Mappers
Type Mappers are a special kind of function which allow Linguini to convert the JSON language item that was retrieved from the language file into any type of your choice.
### Built-In Type Mappers
Linguini has many built-in Type Mappers which can be used inside the `Linguini#get()` method to retrieve language item values as specific types.
Linguini's built-in Type Mappers:
- `String`
- `Boolean`
- `Number`
- `BigInt`
- `Date`
- `RegExp`
- `URL`
For example, let's say you want Linguini to retrieve, not just a plain string, but a [RegExp](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp) object. Linguini has a built-in Type Mapper to convert a JSON language item into a `RegExp`.
Simply import and use `TypeMappers.RegExp` inside the `Linguini#get()` method:
```js
import { TypeMappers } from 'linguini';
// ...
let regex = linguini.get('regexes.hello', 'en', TypeMappers.RegExp);
```
And in our language file:
```json
{
"data": {
"regexes": {
"hello": { "pattern": "hello", "flags": "i" }
}
},
"refs": {}
}
```
Notice how this language item is not just a string, but has 2 properties: `pattern` and `flags`. Using Type Mappers allows Linguini to convert just about any JSON data into any type you wish.
### Custom Type Mappers
If Linguini doesn't have a built-in Type Mapper that suits your needs, you can always create you own. A Type Mapper is simply a function that takes the JSON language item and returns the mapped type.
For example, we can create `Person` Type Mapper, `personTm`:
```js
let personTm = jsonValue => new Person(jsonValue.firstName, jsonValue.lastName);
```
And in our language file, we can define `Person` objects like so:
```json
{
"data": {
"superheroes": {
"batman": { "firstName": "Bruce", "lastName": "Wayne" },
"superman": { "firstName": "Clark", "lastName": "Kent" }
}
},
"refs": {}
}
```
## Variables
Variables allow you to dynamically pass in values to your language items. A variable can be defined in a language file using double curly braces like so: `{{MY_VARIABLE}}`.
Here is a full example:
```json
{
"data": {
"intro": {
"welcome": "Welcome {{FIRST_NAME}} {{LAST_NAME}} to our club!"
}
},
"refs": {}
}
```
Then in our code, we can pass in values for the variables like so:
```js
let welcomeLine = linguini.get('intro.welcome', 'en', TypeMappers.String, {
FIRST_NAME: 'Harley',
LAST_NAME: 'Quinn',
});
console.log(welcomeLine);
// Outputs: "Welcome Harley Quinn to our club!"
```
## References
If you find yourself repeating the same word or phrase over and over in a language file, then references will be your best friend! You can define a commonly used word/phrase once, and then reference it anywhere you need it!
### General References (REF)
General references are defined in a language file using double curly braces with a `REF:` prefix like so: `{{REF:myCategory.myItem}}`, and are used to point to an item in the `"refs"` section of the language file.
Here is an example:
```jsonc
{
"data": {
"intro": {
"myFavoriteColor": "My favorite color is {{REF:aboutMe.favoriteColor}}.",
"yourFavoriteColor": "Is your favorite color {{REF:aboutMe.favoriteColor}} too?"
}
},
"refs": {
// This is a general reference category:
"aboutMe": {
// This is a general reference item:
"favoriteColor": "purple"
}
}
}
```
And in the code:
```js
let myFavoriteColor = linguini.get('intro.myFavoriteColor', 'en', TypeMappers.String);
console.log(myFavoriteColor);
// Outputs: "My favorite color is purple!"
let yourFavoriteColor = linguini.get('intro.yourFavoriteColor', 'en', TypeMappers.String);
console.log(yourFavoriteColor);
// Outputs: "Is your favorite color purple too?"
```
You can also retrieve a reference directly by using `Linguini#getRef()`.
### Common References (COM)
Common References are handy when you want to use the same word/phrase across _multiple_ language files. For example, links are a good place to use Common References, since links are typically displayed alongside translated text, but often stay the same regardless of language.
To use Common References, create a file that matches your language file names, but use `common` as the language code. For example: `lang.common.json`.
In the common language file, you can define references like so:
```jsonc
{
// This is a common reference category:
"links": {
// This is a common reference item:
"github": "https://github.com/KevinNovak"
}
}
```
Then in _any language file_, you can refer to a common reference by using using double curly braces with a `COM:` prefix like so: `{{COM:myCategory.myItem}}`.
So continuing with the above common file example, we can use this link in another language file like so:
```json
{
"data": {
"aboutMe": {
"myGitHub": "Follow me on GitHub at {{COM:links.github}}!"
}
},
"refs": {}
}
```
And in the code:
```js
let myGitHub = linguini.get('aboutMe.myGitHub', 'en', TypeMappers.String);
console.log(myGitHub);
// Outputs: "Follow me on GitHub at https://github.com/KevinNovak!"
```
You can also retrieve a common reference directly by using `Linguini#getCom()`.