@sv443-network/userutils 7.2.2 → 7.3.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @sv443-network/userutils
 
+## 7.3.0
+
+### Minor Changes
+
+- 7e8e147: - Added `tr.forLang()` to get the translation for a specified language code
+  - Added `tr.getTranslations()` to return the translations object for the given or currently active language
+
 ## 7.2.2
 
 ### Patch Changes

package/README.md

@@ -4,7 +4,7 @@
 ## UserUtils
 Lightweight library with various utilities for userscripts - register listeners for when CSS selectors exist, intercept events, create persistent & synchronous data stores, modify the DOM more easily and more.  
   
-Contains builtin TypeScript declarations. Supports ESM and CJS imports via a bundler and UMD / global declaration via `@require`.  
+Contains builtin TypeScript declarations. Supports ESM and CJS imports via a bundler and global declaration via `@require`  
 If you like using this library, please consider [supporting the development ❤️](https://github.com/sponsors/Sv443)
 
 <br>
@@ -63,9 +63,11 @@ View the documentation of previous major releases:
     - [`randomizeArray()`](#randomizearray) - returns a copy of the array with its items in a random order
   - [**Translation:**](#translation)
     - [`tr()`](#tr) - simple translation of a string to another language
+    - [`tr.forLang()`](#trforlang) - specify a language besides the currently set one for the translation
     - [`tr.addLanguage()`](#traddlanguage) - add a language and its translations
     - [`tr.setLanguage()`](#trsetlanguage) - set the currently active language for translations
     - [`tr.getLanguage()`](#trgetlanguage) - returns the currently active language
+    - [`tr.getTranslations()`](#trgettranslations) - returns the translations for the given language or the currently active one
   - [**Colors:**](#colors)
     - [`hexToRgb()`](#hextorgb) - convert a hex color string to an RGB number tuple
     - [`rgbToHex()`](#rgbtohex) - convert RGB numbers to a hex color string
@@ -1960,6 +1962,39 @@ console.log(tr("welcome_name", "John")); // "Willkommen, John"
 
 <br>
 
+### tr.forLang()
+Usage:  
+```ts
+tr.forLang(language: string, key: string, ...values: Stringifiable[]): string
+```  
+  
+Returns the translation of the passed key in the specified language. Otherwise behaves exactly like [`tr()`](#tr)  
+This function does not change the currently active language set by [`tr.setLanguage()`](#trsetlanguage)  
+  
+<details><summary><b>Example - click to view</b></summary>
+
+```ts
+import { tr } from "@sv443-network/userutils";
+
+tr.addLanguage("en", {
+  "welcome_name": "Welcome, %1",
+});
+
+tr.addLanguage("de", {
+  "welcome_name": "Willkommen, %1",
+});
+
+// the language is set to "en"
+tr.setLanguage("en");
+
+console.log(tr("welcome_name", "John"));               // "Welcome"
+// the language doesn't need to be changed:
+console.log(tr.forLang("de", "welcome_name", "John")); // "Willkommen, John"
+```
+</details>
+
+<br>
+
 ### tr.addLanguage()
 Usage:  
 ```ts
@@ -2080,6 +2115,37 @@ tr.getLanguage(): string | undefined
 Returns the currently active language set by [`tr.setLanguage()`](#trsetlanguage)  
 If no language has been set yet, it will return undefined.
 
+<br>
+
+### tr.getTranslations()
+Usage:  
+```ts
+tr.getTranslations(language?: string): Record<string, string> | undefined
+```  
+  
+Returns the translations of the specified language.  
+If no language is specified, it will return the translations of the currently active language set by [`tr.setLanguage()`](#trsetlanguage)  
+If no translations are found, it will return undefined.  
+  
+<details><summary><b>Example - click to view</b></summary>
+
+```ts
+import { tr } from "@sv443-network/userutils";
+
+tr.addLanguage("en", {
+  "welcome": "Welcome",
+});
+
+console.log(tr.getTranslations());     // undefined
+tr.setLanguage("en");
+console.log(tr.getTranslations());     // { "welcome": "Welcome" }
+
+console.log(tr.getTranslations("en")); // { "welcome": "Welcome" }
+
+console.log(tr.getTranslations("de")); // undefined
+```
+</details>
+
 <br><br>
 
 ## Colors:

package/dist/index.global.js

@@ -8,7 +8,7 @@
 // ==UserLibrary==
 // @name         UserUtils
 // @description  Library with various utilities for userscripts - register listeners for when CSS selectors exist, intercept events, create persistent & synchronous data stores, modify the DOM more easily and more
-// @version      7.2.2
+// @version      7.3.0
 // @license      MIT
 // @copyright    Sv443 (https://github.com/Sv443)
 
@@ -1392,18 +1392,22 @@ Has: ${checksum}`);
   // lib/translation.ts
   var trans = {};
   var curLang;
-  function tr(key, ...args) {
+  var trLang = (language, key, ...args) => {
     var _a;
-    if (!curLang)
+    if (!language)
       return key;
-    const trText = (_a = trans[curLang]) == null ? void 0 : _a[key];
+    const trText = (_a = trans[language]) == null ? void 0 : _a[key];
     if (!trText)
       return key;
     if (args.length > 0 && trText.match(/%\d/)) {
       return insertValues(trText, ...args);
     }
     return trText;
+  };
+  function tr(key, ...args) {
+    return trLang(curLang, key, ...args);
   }
+  tr.forLang = trLang;
   tr.addLanguage = (language, translations) => {
     trans[language] = translations;
   };
@@ -1413,6 +1417,9 @@ Has: ${checksum}`);
   tr.getLanguage = () => {
     return curLang;
   };
+  tr.getTranslations = (language) => {
+    return trans[language != null ? language : curLang];
+  };
 
   exports.DataStore = DataStore;
   exports.DataStoreSerializer = DataStoreSerializer;

package/dist/index.js

@@ -1352,18 +1352,22 @@ var SelectorObserver = class {
 // lib/translation.ts
 var trans = {};
 var curLang;
-function tr(key, ...args) {
+var trLang = (language, key, ...args) => {
   var _a;
-  if (!curLang)
+  if (!language)
     return key;
-  const trText = (_a = trans[curLang]) == null ? void 0 : _a[key];
+  const trText = (_a = trans[language]) == null ? void 0 : _a[key];
   if (!trText)
     return key;
   if (args.length > 0 && trText.match(/%\d/)) {
     return insertValues(trText, ...args);
   }
   return trText;
+};
+function tr(key, ...args) {
+  return trLang(curLang, key, ...args);
 }
+tr.forLang = trLang;
 tr.addLanguage = (language, translations) => {
   trans[language] = translations;
 };
@@ -1373,5 +1377,8 @@ tr.setLanguage = (language) => {
 tr.getLanguage = () => {
   return curLang;
 };
+tr.getTranslations = (language) => {
+  return trans[language != null ? language : curLang];
+};
 
 export { DataStore, DataStoreSerializer, Dialog, NanoEmitter, SelectorObserver, addGlobalStyle, addParent, autoPlural, clamp, compress, computeHash, currentDialogId, darkenColor, debounce, decompress, defaultDialogCss, defaultStrings, fetchAdvanced, getSiblingsFrame, getUnsafeWindow, hexToRgb, insertValues, interceptEvent, interceptWindowEvent, isScrollable, lightenColor, mapRange, observeElementProp, openDialogs, openInNewTab, pauseFor, preloadImages, randRange, randomId, randomItem, randomItemIndex, randomizeArray, rgbToHex, setInnerHtmlUnsafe, takeRandomItem, tr };

package/dist/lib/translation.d.ts

@@ -1,7 +1,8 @@
 import type { Stringifiable } from "./types.js";
 /**
  * Returns the translated text for the specified key in the current language set by {@linkcode tr.setLanguage()}
- * If the key is not found in the previously registered translation, the key itself is returned.
+ * Use {@linkcode tr.forLang()} to get the translation for a specific language instead of the currently set one.
+ * If the key is not found in the currently set language, the key itself is returned.
  *
  * ⚠️ Remember to register a language with {@linkcode tr.addLanguage()} and set it as active with {@linkcode tr.setLanguage()} before using this function, otherwise it will always return the key itself.
  * @param key Key of the translation to return
@@ -9,8 +10,10 @@ import type { Stringifiable } from "./types.js";
  */
 declare function tr(key: string, ...args: Stringifiable[]): string;
 declare namespace tr {
+    var forLang: (language: string, key: string, ...args: Stringifiable[]) => string;
     var addLanguage: (language: string, translations: Record<string, string>) => void;
     var setLanguage: (language: string) => void;
     var getLanguage: () => string;
+    var getTranslations: (language?: string | undefined) => Record<string, string> | undefined;
 }
 export { tr };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sv443-network/userutils",
   "libName": "UserUtils",
-  "version": "7.2.2",
+  "version": "7.3.0",
   "description": "Library with various utilities for userscripts - register listeners for when CSS selectors exist, intercept events, create persistent & synchronous data stores, modify the DOM more easily and more",
   "main": "dist/index.js",
   "module": "dist/index.mjs",