> For the complete documentation index, see [llms.txt](https://docs.angular-package.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.angular-package.dev/sass/translator-v0.1.0/dictionary/dictionary.merge.md).

# dictionary.merge()

The `dictionary.merge()` function returns global dictionary(if in use) merged with multiple dictionaries from [`$dictionary`](#usddictionary) optionally merged in [`$key`](#usdkey-null).

{% hint style="info" %}
Global dictionary is in use on [`$dictionary-global`](/sass/translator-v0.1.0/dictionary/dictionary.variables.md#usddictionary-global-true) set to `true`, or by setting [`$global`](#usdglobal-null) argument to `true`.
{% endhint %}

{% code lineNumbers="true" %}

```scss
// Sass.
@use 'sass:list';
@use 'sass:meta';

// Variables.
@forward 'dictionary.variables';
@use 'dictionary.variables' as variables;

// Functions.
@use 'dictionary.get.function' as *;
@use 'dictionary.is-global.function' as *;

// Modules.
@use '../../map';

// The `translator.dictionary-merge()` or `dictionary.merge()` function.
@function merge($key: null, $dictionary, $global: null) {
  @if type-of($dictionary) == list {
    $retrieved-dictionary: ();
    @each $dictionary in if(list.separator($dictionary) == comma, $dictionary, ($dictionary,)) {
      @if type-of($dictionary) == list and list.length($dictionary) > 1 {
        $dictionary: map.retrieve(pick, list.nth($dictionary, 1), list.nth($dictionary, 2));
      }

      $retrieved-dictionary: map.deep-merge($retrieved-dictionary, $dictionary);
    }

    $dictionary: $retrieved-dictionary;
  }

  $dictionary: if(
    $key,
    map.merge(get($global: $global), list.append($key, $dictionary)...),
    map.deep-merge(get($global: $global), $dictionary)
  );
  @if is-global($global) {
    variables.$dictionary: $dictionary;
  }
  @return $dictionary;
}
```

{% endcode %}

{% embed url="<https://github.com/angular-package/sass/blob/main/translator/dictionary/_dictionary.merge.function.scss>" %}

### Parameters

#### `$key: null`

The optional key under which multiple dictionaries from [`$dictionary`](#usddictionary) are being merged.

#### `$dictionary: ()`

Dictionary or multiple dictionaries of map or list type(dictionary keys, dictionary keys) to merge with a global dictionary(if in use) optionally in [`$key`](#usdkey-null).

{% hint style="info" %}
Dictionary as list indicates picking the dictionary of key, e.g. `$dictionary (class, var)` indicates to pick the `class` and `var` keys of `$dictionary`.
{% endhint %}

#### `$global: null`

A `bool` value indicates whether to use a global dictionary. Default, `null`, then [`$dictionary-global`](/sass/translator-v0.1.0/dictionary/dictionary.variables.md) is checked.

### Return

The return value is a dictionary consists of global dictionary(if in use) and multiple dictionaries from [`$dictionary`](#usddictionary) optionally merged in [`$key`](#usdkey-null).

## Examples

### Merge in `$key`

```scss
// Use.
@use '@angular-package/sass/translator';

// 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),
);

@debug translator.$dictionary; // (word: translation)

// merge in `class` key
@debug translator.dictionary-merge(class, (prefix: spectre, suffix: end));
// (word: translation, class: (prefix: spectre, suffix: end))

```

### Merge in nested `$key`

```scss
// merge in nested (accordion, class) key
@debug translator.dictionary-merge((accordion, class), (prefix: spectre, suffix: end));
// (word: translation, accordion: (class: (prefix: spectre, suffix: end)))

```

### Multiple dictionaries

```scss
// merge in nested (accordion, class) (accordion, var) key + pick key
@debug translator.dictionary-merge(accordion, ($-dictionary class, $-dictionary var));
@debug translator.dictionary-merge(accordion, $-dictionary (class, var));
// (word: translation, accordion: (class: (prefix: class-prefix, suffix: class-suffix), var: (prefix: var-prefix, suffix: var-suffix)))

```