xaymar/JS-DSI18n
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

project: Improve readme

Browse Source
This commit was merged in pull request #1.
This commit is contained in:
Michael Fabian 'Xaymar' Dirks
2018-11-29 03:06:41 +01:00
committed by Michael Fabian Dirks
parent 3a02539ed6
commit a2f0659bce
1 changed files with 16 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files
readme.md
+16 -13
View File
@@ -1,49 +1,52 @@
# I18n (JavaScript) # I18n (JavaScript)
Very simple JavaScript library for handling translations. Supports Node.js, Electron and other JavaScript based code runners. Very simple JavaScript library for handling translations. Supports Node.js, Electron and other JavaScript based code runners.
## Features: # Features:
* Simple modern API with Promises and full Documentation. * Simple modern API with Promises and full Documentation.
* Support for languages with more than one base language and per language base language overrides. * Support for languages with more than one base language and per language base language overrides.
* Cached translation chains for quick and recursion free key lookups. * Cached translation chains for quick and recursion free key lookups.
# Maintenance, Donations, etc.
This codes maintenance is funded through [Patreon](https://www.patreon.com/Xaymar). If you think this code is useful to you, consider donating a few bucks.
# License # License
Licensed under Affero GNU GPLv3. See license.txt for more information. Licensed under Affero GNU GPLv3. See license.txt for more information.
# Documentation # Documentation
`i18n.js` is fully documented using JSDoc, a format IDEs should be able to display. If in any case your IDE is not showing this information, your first reference should be `i18n.js`, not this readme. `i18n.js` is fully documented using JSDoc, a format IDEs should be able to display. If in any case your IDE is not showing this information, your first reference should be `i18n.js`, not this readme.
## I18n ### I18n
The class that contains all the translation data. The class that contains all the translation data.
### constructor(string defaultLanguage, string baseLanguageKey = '_base') ##### constructor(string defaultLanguage, string baseLanguageKey = '\_base')
Creates a new I18n object when called with `new I18n('mylanguage')`. Will set up internal structures and variables for later use. Throws exceptions. Creates a new I18n object when called with `new I18n('mylanguage')`. Will set up internal structures and variables for later use. Throws exceptions.
### bool hasLanguage(string language) ##### bool hasLanguage(string language)
Check if a language is known to this I18n object. Returns true if known. Throws exceptions. Check if a language is known to this I18n object. Returns true if known. Throws exceptions.
### createLanguage(string language) ##### createLanguage(string language)
Create a new empty language, or replaces a loaded one with an empty one. Throws exceptions. Create a new empty language, or replaces a loaded one with an empty one. Throws exceptions.
### Promise(string) loadLanguage(string language, File|Blob|object|string data, string encoding = 'utf-8') ##### Promise(string) loadLanguage(string language, File|Blob|object|string data, string encoding = 'utf-8')
Load a language from a File, Blob, object or string as JSON data, and store it as the language. Returns a Promise, which will resolve once it is done loading and parsing and the result will contain the loaded language name. Throws exceptions. Load a language from a File, Blob, object or string as JSON data, and store it as the language. Returns a Promise, which will resolve once it is done loading and parsing and the result will contain the loaded language name. Throws exceptions.
### Promise(string) saveLanguage(string language) ##### Promise(string) saveLanguage(string language)
Save a language to a string as JSON data. Returns a Promise which will resolve with the JSON data string once done. Modifying the language before the returned Promise is done can result in corrupt data. Throws exceptions. Save a language to a string as JSON data. Returns a Promise which will resolve with the JSON data string once done. Modifying the language before the returned Promise is done can result in corrupt data. Throws exceptions.
### destroyLanguage(string language) ##### destroyLanguage(string language)
Destroy a language, thus clearing any references to data in it. Throws exceptions. Destroy a language, thus clearing any references to data in it. Throws exceptions.
### bool clearKey(string language, string key) ##### bool clearKey(string language, string key)
Remove a key from a language. Returns true if the key was removed. Throws exceptions. Remove a key from a language. Returns true if the key was removed. Throws exceptions.
### bool setKey(string language, string key, any value, bool force = true) ##### bool setKey(string language, string key, any value, bool force = true)
Set a key in a language to a new value, optionally overwriting the previous content (defaults to true). Returns true if successful. Throws exceptions. Set a key in a language to a new value, optionally overwriting the previous content (defaults to true). Returns true if successful. Throws exceptions.
### any getKey(string language, string key) ##### any getKey(string language, string key)
Get the value of a key in a language. Returns the value of the key if known, otherwise throws an exception. Get the value of a key in a language. Returns the value of the key if known, otherwise throws an exception.
### string translate(string key, string language) ##### string translate(string key, string language)
Translate a given key to the language selected. Returns the translated string or the original key if it was not found. Throws exceptions. Translate a given key to the language selected. Returns the translated string or the original key if it was not found. Throws exceptions.
### Promise domTranslate(string language, string property = 'data-i18n', function resolver = string function(string language, string key, Node element), function applier = bool function(string language, string key, string translated, Node element)) ##### Promise domTranslate(string language, string property = 'data-i18n', function resolver = string function(string language, string key, Node element), function applier = bool function(string language, string key, string translated, Node element))
Automatically translate all elements in the current DOM which have the attribute `property`. Returns a Promise which resolves when the translation is complete. Throws exceptions. Automatically translate all elements in the current DOM which have the attribute `property`. Returns a Promise which resolves when the translation is complete. Throws exceptions.