Langer DISCORDBOTS

LANGER JS is a library to create web pages with multiple languages. Compatible with native JS and React, Now also compatible for DISCORD BOTS!

install

To install this version you can do it via npm

npm i [email protected]

it is recommended to first read the documentation of the normal version in order to better understand

Import

always remember to import the library in all files that need to use it.

const LANGER = require("langerjs-discord")

Languages

Langer uses .json files as languages, you must create a folder where you contain your languages

Example of a .json Language

{
    "key":"I am a lenguage.json example!",
    "settings": {
        "keyInAnotherKey":" settings"
    },
}

Folders as languages

In this version languages can also be folders example:

├── your_language_folder

    ├── ES.json
    ├── EN.json

    ├── FR
        ├── main.json
        ├── another_folder
            ├── main2.json

    ├── KO.json 
    ...

in the end this will combine in the same object all the .json files contained in that folder, avoid repeating keys.

initialization

To initialize, use the LANGER.Create() function, passing it the desired settings, it is recommended to initialize in index.js

const LANGER = require("langerjs-discord")

// await is not required but it is recommended to place it.
await LANGER.Create({
    functions: true,//Boolean: activate the functions in the json strings.
    defaultText: "(undefined)",
    rout: "json/", //string: route where are your languages
    languages: ["ES","EN"], //Array<String>: Array of the names of all the languages to be used by your application.
    fetch:{ //fetch settings
        usePrimaryToDefault:true, //will make that when a key is not found, it will look for it in the primary language (the first noted) and if not found, the defaultText will be used finally
    
        //function to be executed at the end of the configuration or after the language are preloaded
        onReady(cache) {
            console.log(`${cache.size\} languages loaded!`)
        },
        watch: false, //boolean allow the watch mode - Every time a language is edited it will be changed without the need to restart the process

        //function will be executed every time a language is updated by the watch mode
        onLanguageUpdate(language) {
            console.log(`${language.name} language updated!`)
        },
    },

});

Properties

| Property | Description | default | |--|--|--| | functions | Boolean Activate or deactivate the functions in the json. | true |
| rout | String Route where your languages are | null | | languages | Array<String> Array of the names of all the languages to be used by your application | [] | | defaultText | String or Null Text that will be used in case a key is not found in a language. If it is null the name of the key will be used instead of a replacement text | "(undefined)" | | fetch | Object fetch settings | Object | | fetch.usePrimaryToDefault | Boolean will cause when a key is not found, it will look for it in the primary language (the first noted) and, if not found, the defaultText will be used eventually | false | | fetch.onReady | Function to be executed at the end of the configuration or after the languages are loaded. | null | | fetch.watch | boolean allow watch mode - every time you edit a language file, it will be updated without having to restart the process. | false | | fetch.onLanguageUpdate | Function will be executed every time a language is updated by watch mode | null |

Use

We will assume that you are in a Prefix Commands handler

To start using a language you must use the method LANGER.Controller passing it the language to use, this will return a KeyParser which will be used to obtain some key from the language

Now to obtain a key we will use the KeyParser as a function passing it a key

// Example Code
const Discord = require("discord.js")
const LANGER = require("langerjs-discord")

module.exports = {
    name:"example",
    description:"",
    execute: (client,message,args) => {
        // Use the LANGER.Controller method to create a KeyParser
        let keyParser = LANGER.Controller("ES");

        // Use the previously created KeyParser as a function to get the content of your key.
        message.reply( keyParser("key") )
        
    }
}

NOTE

LANGER does not depend on discord.js it was just used as an example could use any other alternative.

JSON functions

The functions are used to return something in the json obtained Example

{
    "key": "This is an example using functions mat(4 + 5)"
}

NOTE

It should be noted that the mat function was removed in version 6.0

Default Functions

lang(key) //Returns the content of a language key.

Create your own functions

const LANGER = require("langerjs-discord");

//example
LANGER.setFunctions(
    function hellow(value) {
        return "¡Hellow World!" + value; //Functions MUST return a String
    },
    function tree(value) {
        return "Forest"
    }
);

Disable functions

To disable the functions in some KeyParser you should only pass it as the 2nd or 3rd parameter true

const LANGER = require("langerjs-discord");

let keyParser = LANGER.Controller("ES");

// example of disabling functions
console.log( KeyParser("key",{},true) )

// Or if your KeyParser doesn't have any placeholders you can just put true as the second parameter to disable the functions.
console.log( KeyParser("key",true) )

fetch

fetch settings

await LANGER.Create({
    fetch:{ //fetch settings
         
        usePrimaryToDefault:true, //will make that when a key is not found, it will look for it in the primary language (the first noted)and if not found, the defaultText will be used finally
        
        //function to be executed at the end of the configuration or after the language are preloaded
        onReady: (cache) => {
            console.log(`${cache.size} languages loaded`)
        }
        
        watch: false, //allow the watch mode - Every time a language is edited it will be changed without the need to restart the process
        
        //function will be executed every time a language is updated by the watch mode
        onLanguageUpdate(language) {
            console.log(`${language.name} language updated!`)
        }
        
    }
});

onReady

function will be executed after the configuration is done or after the languages are loaded by fetch.all

await LANGER.Create({
    fetch: {
        onReady(cache) {
            console.log(`${cache.size} languages loaded!`)
        }
    }
})

onLanguageUpdate

Function will be executed every time a language is updated by watch mode

interface LanguageUpdate { // properties of the event param
    /** Absolute file path */
    file: string,
    /** Language Name */
    name: string,
    /** Language Object */
    content: Object,
}

await LANGER.Create({
    fetch: {
        /** @param {LanguageUpdate} language - info of the language updated */
        onLanguageUpdate(language) {
            console.log(`${language.name} language Updated!`)
        }
    }
})

usePrimaryToDefault

will cause when a key is not found, it will look for it in the main language (the first noted) and, if not found, the defaultText will be used finally

if in our configurations we indicate the languages ("ES","EN") the main language will be ES

await LANGER.Create({
    languages: ["ES","EN"]
})

suppose we have more than one language and one of them is incomplete:

// ES.json
{
    "key": "por defecto",
    "keyspanish": "está key solo existirá en español"
}
// EN.json (incomplete)
{
    "key": "default"
}

when wanting to use those keys and having fetch.usePrimaryToDefault activated, the following will happen

//Now in v7 with fetch.usePrimaryToDefault enabled

//result when we use ES 
key -> "por defecto"
keyspanish -> "esta key solo existirá en español"

//result when we use EN 

key -> "default"
keyspanish -> "esta key solo existirá en español"

although keyspanish does not exist in "EN" the keyspanish of the language "ES" was used because this is the main language if it is did not exist either, the defaultText would be used

//before in v6 

//result when we use ES 
key -> "por defecto"
keyspanish -> "esta key solo existirá en español"

//result when we use EN 

key -> "default"
keyspanish -> "(undefined)"

Placeholders

Placeholders can be used to display something that is not static, like a username

Placeholds are used differently in this version.

The syntax of the placeholders in the json is the following:

{
    "test": "Hellow, %user%"
}

To use the placeholders in this version, you must pass as a second parameter an object with the placeholders you want to your KeyParser

const LANGER = require("langerjs-discord");

let KeyParser = LANGER.Controller("ES");

console.log( KeyParser("test", { user: "Example" } ) )
// KeyParser will return "Hellow, Example"

Utilities

utilities are functions that can be useful to you, such as to check if a language exists in the list of languages passed in the configurations

const LANGER = require("langerjs-discord");

LANGER.has("es");

LANGER.findHas("es");

LANGER.languagesArray();

LANGER.BuildLanguages()

| function | Description | |--|--| | LANGER.has | parameter String Checks if a language exists (regardless of its case) returns true if it exists and false if it doesn't | | LANGER.findHas | parameter String Checks if a language exists (regardless of its case) returns the exact name of the language if it exists and undefined if it doesn't | | LANGER.languagesArray | returns an array of all existing loaded languages. |

LANGER.BuildLanguages

Allows to join/minfify those languages that are folders in a single file

LANGER.BuildLanguages({
    rout:"json", //Path where your languages are
    outDir:"dist/json", //Path where the processed languages will be created
    minify: false, //minify files (remove spaces, tabs and newlines)
})

Suppose your languages folder looks like this

├── your_language_folder

    ├── ES.json
    ├── EN.json

    ├── FR
        ├── main.json
        ├── another_folder
            ├── main2.json

    ├── KO.json 
    ...

After using LANGER.BuildLanguages the folder you specified will have the languages bundled and/or minified.

├── your_out_language_folder

    ├── ES.json
    ├── EN.json
    ├── FR.json
    ├── KO.json 
    ...

utilities for KeyParser

const LANGER = require("langerjs-discord");

let KeyParser = LANGER.Controller("EN");

KeyParser.lang
KeyParser.languageName
KeyParser.entries()
KeyParser.keys()
KeyParser.values()

KeyParser.getArray("key to find")
KeyParser.applyToString("text to process %hi%!", {hi: "LangerJS"}, false)

| function | Description | |--|--| | KeyParser.lang | object of the language being used | | KeyParser.languageName | name of the language being used | | KeyParser.entries() | will return the entries of the language being used in the form of Array | | KeyParser.keys() | will return all the keys of the language being used as an Array | | KeyParser.values() | will return all the keys of the language being used as an Array | | KeyParser.getArray(key) | Get an Array of the language | | KeyParser.applyToString(text, placeholders, dontFunctions) | Similar to KeyParser(), but instead of passing a key it is passed the text to process using placeholders and/or functions |