refactor(translator): add 1.0.0 version with only global dictionary…

…, `0.1.0` is deprecated.

translator/_index.scss

@@ -1,5 +1 @@
-@forward 'dictionary' as dictionary-*;
-@forward 'translate' as translate-*;
-@forward 'dictionary/dictionary.variables';
-@forward 'translator.dictionary.function';
-@forward 'translator.translate.function';
+@forward 'v0.1.0';

translator/_translator.spec.scss

@@ -1,5 +1,5 @@
 // Translator.
-@use '../translator';
+@use 'v1.0.0' as translator;
 
 // ---
 // Dictionary
@@ -51,9 +51,6 @@ $-dictionary: (
 // merge then pick dictionary
 @debug translator.dictionary-pick(sub-dictionary); // (sub-dictionary: (class: (prefix: class-prefix, suffix: class-suffix)))
 
-// check whether global dictionary is in use
-@debug translator.dictionary-is-global(); // true
-
 // check modified dictionary
 @debug translator.$dictionary; // (word: translation, sub-dictionary: (class: (prefix: class-prefix, suffix: class-suffix)))
 

translator/v0.1.0/_index.scss

@@ -0,0 +1,5 @@
+@forward 'dictionary' as dictionary-*;
+@forward 'translate' as translate-*;
+@forward 'dictionary/dictionary.variables';
+@forward 'translator.dictionary.function';
+@forward 'translator.translate.function';

translator/_translator.dictionary.function.scss → translator/v0.1.0/_translator.dictionary.function.scss

@@ -3,7 +3,7 @@
 @use 'sass:meta';
 
 // Modules.
-@use '../map';
+@use '../../map';
 @use 'dictionary';
 
 // Status: DONE

translator/v0.1.0/_translator.spec.scss

@@ -0,0 +1,80 @@
+// Translator.
+@use '../../translator';
+
+// ---
+// Dictionary
+// ---
+$-dictionary: (
+  class: (prefix: class-prefix, suffix: class-suffix),
+  prefix: spectre,
+  suffix: end,
+
+  // Sizes.
+  (extra large, 'extra large', extra-large): xl,
+  (extra small, 'extra small', extra-small): xs,
+
+  large: lg,
+  medium: md,
+  small: sm,
+
+  size: s,
+);
+
+// Use the global dictionary.
+// translator.$dictionary-global: false; // set the dictionary global to false
+// @debug translator.$dictionary-global; // true
+// @debug translator.$dictionary; // (word: translation)
+
+// Working on the global dictionary.
+// set the (word:translation)
+// @debug translator.dictionary-set(prefix, spectre); // (word: translation, prefix: spectre)
+// @debug translator.dictionary-set(suffix, end); // (word: translation, prefix: spectre, suffix: end)
+
+// set the dictionary under the key `class`
+// @debug translator.dictionary-set(class, (prefix: spectre, suffix: end)); // (word: translation, class: (prefix: spectre, suffix: end))
+
+// merge `$-dictionary` with a global dictionary
+// @debug translator.dictionary-merge($dictionary: $-dictionary); // (word: translation, class: (prefix: class-prefix, suffix: class-suffix), prefix: spectre, suffix: end, (extra large, "extra large", extra-large): xl, (extra small, "extra small", extra-small): xs, large: lg, medium: md, small: sm, size: s)
+
+// merge `$-dictionary` under the sub-dictionary key with a global dictionary
+// @debug translator.dictionary-merge(sub-dictionary, $dictionary: $-dictionary); // (word: translation, sub-dictionary: (class: (prefix: class-prefix, suffix: class-suffix), prefix: spectre, suffix: end, (extra large, "extra large", extra-large): xl, (extra small, "extra small", extra-small): xs, large: lg, medium: md, small: sm, size: s))
+
+// merge class from `$-dictionary` under the sub-dictionary key with a global dictionary
+// @debug translator.dictionary-merge(sub-dictionary, $dictionary: $-dictionary class); // (word: translation, sub-dictionary: (class: (prefix: class-prefix, suffix: class-suffix), prefix: spectre, suffix: end, (extra large, "extra large", extra-large): xl, (extra small, "extra small", extra-small): xs, large: lg, medium: md, small: sm, size: s))
+
+// merge class from `$-dictionary` under the sub-dictionary key with a global dictionary
+@debug translator.dictionary-merge(sub-dictionary, $-dictionary class); // (word: translation, sub-dictionary: (class: (prefix: class-prefix, suffix: class-suffix)))
+
+// get dictionary
+@debug translator.dictionary-get(sub-dictionary); // (class: (prefix: class-prefix, suffix: class-suffix))
+
+// merge then pick dictionary
+@debug translator.dictionary-pick(sub-dictionary); // (sub-dictionary: (class: (prefix: class-prefix, suffix: class-suffix)))
+
+// check whether global dictionary is in use
+@debug translator.dictionary-is-global(); // true
+
+// check modified dictionary
+@debug translator.$dictionary; // (word: translation, sub-dictionary: (class: (prefix: class-prefix, suffix: class-suffix)))
+
+// get flattened dictionary by picking from the global dictionary
+@debug translator.dictionary((sub-dictionary, class)); // (word: translation, prefix: class-prefix, suffix: class-suffix)
+
+// ---
+// Translate
+// ---
+// merge before translate
+@debug translator.dictionary-merge($dictionary: $-dictionary);
+
+// check dictionary
+@debug translator.dictionary(); // (word: translation, prefix: spectre, suffix: end, (extra large, "extra large", extra-large): xl, (extra small, "extra small", extra-small): xs, large: lg, medium: md, small: sm, size: s)
+
+// do some translates
+@debug translator.translate-string(prefix, (sub-dictionary, class)); // class-prefix
+@debug translator.translate-string(suffix); // end
+@debug translator.translate-string(extra-large); // xl
+
+// use translate
+@debug translator.translate(extra large); // xl
+@debug translator.translate((extra large) (extra small)); // xl xs
+@debug translator.translate(prefix width suffix, (sub-dictionary, class)); // class-prefix width class-suffix

translator/dictionary/_dictionary.get.function.scss → translator/v0.1.0/dictionary/_dictionary.get.function.scss

@@ -7,11 +7,11 @@
 @use 'dictionary.variables' as variables;
 
 // Functions.
-@use '../../meta/meta.of-type.function' as *;
+@use '../../../meta/meta.of-type.function' as *;
 @use 'dictionary.is-global.function' as *;
 
 // Modules.
-@use '../../map';
+@use '../../../map';
 
 // Status: DONE
 // The `dictionary.get()` function returns the global dictionary(if in use) along with `$dictionary` and/or from `$key`.

translator/dictionary/_dictionary.merge.function.scss → translator/v0.1.0/dictionary/_dictionary.merge.function.scss

@@ -11,7 +11,7 @@
 @use 'dictionary.is-global.function' as *;
 
 // Modules.
-@use '../../map';
+@use '../../../map';
 
 // Status: DONE
 // The `dictionary.merge()` function returns a global dictionary(if in use) merged with multiple dictionaries from `$dictionary` optionally merged in `$key`.

translator/dictionary/_dictionary.pick.function.scss → translator/v0.1.0/dictionary/_dictionary.pick.function.scss

@@ -6,7 +6,7 @@
 @use 'dictionary.variables' as variables;
 
 // Modules.
-@use '../../map';
+@use '../../../map';
 
 // Functions.
 @use 'dictionary.is-global.function';

translator/dictionary/_dictionary.set.function.scss → translator/v0.1.0/dictionary/_dictionary.set.function.scss

@@ -2,7 +2,7 @@
 @use 'sass:meta';
 
 // Modules.
-@use '../../map';
+@use '../../../map';
 
 // Functions.
 @use 'dictionary.is-global.function' as *;

translator/translate/_translate.list.function.scss → translator/v0.1.0/translate/_translate.list.function.scss

@@ -2,7 +2,7 @@
 @use 'sass:list';
 
 // Functions.
-@use '../../list/has/has.list.function' as *;
+@use '../../../list/has/has.list.function' as *;
 @use '../translator.dictionary.function';
 @use 'translate.nth.function';
 

translator/v1.0.0/_index.scss

@@ -0,0 +1,5 @@
+@forward 'dictionary' as dictionary-*;
+@forward 'translate' as translate-*;
+@forward 'dictionary/dictionary.variables';
+@forward 'translator.dictionary.function';
+@forward 'translator.translate.function';

translator/v1.0.0/_translator.dictionary.function.scss

@@ -0,0 +1,56 @@
+// Sass.
+@use 'sass:list';
+
+// Modules.
+@use '../../map';
+@use 'dictionary';
+
+// Status: DONE
+// The `translator.dictionary()` function returns global dictionary(flattened map), optionally merged with dictionaries retrieved from `$keys`.
+// @param `$keys...` Keys to merge the dictionaries under these keys with a dictionary.
+// @returns The return value is a flattened map dictionary consisting of (word:translation).
+@function dictionary($keys...) {
+  @return map.remove-type(
+    if(
+      list.length($keys) > 0,
+      map.deep-merge-key(dictionary.get(), $keys...),
+      dictionary.get()
+    ),
+    map
+  );
+}
+
+// Variables.
+// $-dictionary-example: (
+//   general: (word: słowo, (wrapper, wrap): owijka, (technology, technologia): tech, color: c),
+//   class: (prefix: class-prefix, separator: class-separator, suffix: class-suffix, calendars: (calendar: cal), labels: (label: lab)),
+//   prefix: spectre,
+//   border: b,
+//   color: c,
+//   separator: '-',
+//   suffix: end,
+//   outline: o,
+//   var: (prefix: var-prefix, suffix: var-suffix),
+// );
+
+// Examples.
+// Gets the global dictionary.
+// @debug dictionary(); // (word: translation)
+
+// Merge the global dictionary.
+// $-test: dictionary.merge(null, $-dictionary-example);
+
+// Set the global dictionary.
+// $-test: dictionary.set(global, this is global translation);
+
+// Gets the general dictionary.
+// @debug dictionary(general); // (word: słowo, prefix: spectre, border: b, color: c, separator: "-", suffix: end, outline: o, global: this is global translation, (wrapper, wrap): owijka, (technology, technologia): tech)
+
+// Gets nested (class, calendars) dictionary.
+// @debug dictionary((class, calendars)); // (word: translation, prefix: spectre, border: b, color: c, separator: "-", suffix: end, outline: o, global: this is global translation, calendar: cal)
+
+// Gets the general and nested (class, calendars) dictionary.
+// @debug dictionary(general, (class, calendars)); // (word: słowo, prefix: spectre, border: b, color: c, separator: "-", suffix: end, outline: o, global: this is global translation, (wrapper, wrap): owijka, (technology, technologia): tech, calendar: cal)
+
+// Get multiple nested.
+// @debug dictionary((class, calendars), (class, labels), class); // (word: translation, prefix: class-prefix, border: b, color: c, separator: class-separator, suffix: class-suffix, outline: o, global: this is global translation, calendar: cal, label: lab)

translator/v1.0.0/_translator.translate.function.scss

@@ -0,0 +1,61 @@
+// Sass.
+@use 'sass:list';
+@use 'sass:map';
+@use 'sass:meta';
+
+// Functions.
+@use 'translator.dictionary.function';
+
+// Modules.
+@use 'dictionary';
+@use 'translate';
+
+// Status: DONE
+// The `translator.translate()` function translates `list`, `map`, or `string` with a global dictionary, optionally with a dictionary of `$keys`.
+// @param `$words` The words in `list`, `map`, or `string` to translate.
+// @arbitrary `$keys...` Keys of the dictionaries that are used to translate `$words`.
+// @returns The return value is the translated `list`, `map`, or `string` depending on the given `$words`.
+@function translate($words, $keys...) {
+  @return meta.call(map.get((
+      list: meta.get-function(list, false, translate),
+      map: meta.get-function(map, false, translate),
+      string: meta.get-function(string, false, translate),
+    ),
+    meta.type-of($words)),
+    $words,
+    $keys...
+  );
+}
+
+// Examples.
+// $-dictionary-example: dictionary.merge(null, (
+//   (extra large, 'extra large', extra-large): xl,
+//   (extra small, 'extra small', extra-small): xs,
+//   class: (prefix: class-prefix, separator: class-separator, suffix: class-suffix, calendars: (calendar: cal), labels: (label: lab)),
+//   general: (word: słowo, (wrapper, wrap): owijka, (technology, technologia): tech, border: b, outline: o, color: c),
+//   large: lg,
+//   medium: md,
+//   prefix: spectre,
+//   small: sm,
+//   suffix: end,
+// ));
+
+// String.
+// @debug translate(wrapper, general); // owijka
+// @debug translate(technology, general); // tech
+
+// List
+// @debug translate(prefix (border, outline) color); // spectre (border, outline) color
+
+// Map
+// @debug translate((word: prefix (border, outline) color)); // (word: spectre (border, outline) color)
+// @debug translate((word: wrapper), general); // (word: owijka)
+
+// Use dictionaries from keys
+// @debug translate(prefix (border, outline) color, general); // spectre (b, o) c
+// @debug translate((wrapper, technology, prefix)); // wrapper, technology, spectre
+// @debug translate((wrapper, technology), general); // owijka, tech
+// @debug translate((wrapper, technology) color, general); // (owijka, tech) c
+
+// Nested dictionary calendars
+// @debug translate(calendar, (class, calendars)); // cal

translator/v1.0.0/dictionary/_dictionary.get.function.scss

@@ -0,0 +1,38 @@
+// Variables.
+@forward 'dictionary.variables';
+@use 'dictionary.variables' as variables;
+
+// Modules.
+@use '../../../map';
+
+// Status: DONE
+// The `dictionary.get()` function returns a global dictionary, optionally a dictionary from `$key`.
+// @param `$key` An optional key to retrieve a dictionary from a global dictionary.
+// @param `$default` The default returned value if dictionary is `null`.
+// @returns The return value is a dictionary, optionally from `$key`. If `null` returned value is `$default`.
+@function get($key: null, $default: null) {
+  @return if(
+    $key,
+    if(
+      type-of(map.get(variables.$dictionary, $key)) == map,
+      map.get(variables.$dictionary, $key),
+      $default
+    ),
+    variables.$dictionary
+  );
+}
+
+// Examples.
+// Gets the global dictionary
+// @debug get(); // (word: translation)
+
+// Gets the global dictionary of key (not translation)
+// @debug get(word); // null
+
+// Gets nested key
+// variables.$dictionary: map.merge(variables.$dictionary, (test: (ok: (first: accept, second: do))));
+// @debug get((test, ok)); // (first: accept, second: do)
+// @debug get((word, wrong)); // null
+
+// Gets the `$default`
+// @debug get(word, exist); // exist

translator/v1.0.0/dictionary/_dictionary.merge.function.scss

@@ -0,0 +1,57 @@
+// Sass.
+@use 'sass:list';
+@use 'sass:meta';
+
+// Variables.
+@forward 'dictionary.variables';
+@use 'dictionary.variables' as variables;
+
+// Functions.
+@use 'dictionary.get.function' as *;
+
+// Modules.
+@use '../../../map';
+
+// Status: DONE
+// The `dictionary.merge()` function returns a global dictionary merged with `$dictionary` and/or multiple `$dictionaries`, optionally merged in `$key`.
+// @param `$key` The optional key under which `$dictionary` and multiple `$dictionaries` are being merged.
+// @param `$dictionary` Dictionary of map type to merge with a global dictionary.
+// @arbitrary `$dictionaries...` Additional dictionaries along with a `$dictionary` to merge with a global dictionary.
+// @returns The return value is global dictionary merged with `$dictionary` and/or multiple `$dictionaries`, optionally merged in `$key`.
+@function merge($key: null, $dictionary, $dictionaries...) {
+  $retrieved-dictionary: ();
+  @each $dictionary in list.join(($dictionary, ), $dictionaries, comma) {
+    $retrieved-dictionary: map.deep-merge(
+      $retrieved-dictionary,
+      if(meta.type-of($dictionary) == list, map.pick(list.nth($dictionary, 1), list.nth($dictionary, 2)...), $dictionary)
+    );
+  }
+
+  variables.$dictionary: if(
+    $key,
+    map.merge(get() or (), list.append($key, $retrieved-dictionary)...),
+    map.deep-merge(get() or (), $retrieved-dictionary)
+  );
+
+  @return variables.$dictionary;
+}
+
+// Examples.
+// $-dictionary: (
+//   (extra large, 'extra large', extra-large): xl,
+//   (extra small, 'extra small', extra-small): xs,
+//   class: (prefix: class-prefix, suffix: class-suffix),
+//   large: lg,
+//   medium: md,
+//   prefix: spectre,
+//   size: s,
+//   small: sm,
+//   suffix: end,
+//   var: (prefix: var-prefix, suffix: var-suffix),
+// );
+
+// merge in `class` key
+// @debug merge(class, (prefix: spectre, suffix: end)); // (word: translation, class: (prefix: spectre, suffix: end))
+
+// merge in nested (accordion, class) key
+// @debug merge((accordion, class), (prefix: spectre, suffix: end)); // (word: translation, class: (prefix: spectre, suffix: end), accordion: (class: (prefix: spectre, suffix: end)))