# translator.translate()

The `translator.translate()` function translates [`list`](https://sass-lang.com/documentation/modules/list), [`map`](https://sass-lang.com/documentation/modules/map/), or [`string`](https://sass-lang.com/documentation/modules/string) with a global dictionary, optionally with a dictionary of [`$keys`](#usdkeys...).

{% code lineNumbers="true" %}

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

// Functions.
@use 'translator.dictionary.function';

// Modules.
@use 'dictionary';
@use 'translate';

// The `translator.translate()` function.
@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...
  );
}
```

{% endcode %}

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

### Parameters

#### `$words`

The words in [`list`](https://sass-lang.com/documentation/modules/list), [`map`](https://sass-lang.com/documentation/modules/map), or [`string`](https://sass-lang.com/documentation/modules/string) to translate.

#### `$keys...`

Keys of the dictionaries that are used to translate [`$words`](#usdwords).

### Return

The return value is the translated [`list`](https://sass-lang.com/documentation/modules/list), [`map`](https://sass-lang.com/documentation/modules/map), or [`string`](https://sass-lang.com/documentation/modules/string) depending on the given [`$words`](#usdwords).

## Examples

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

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

### Translate `string`

Translates [`string`](https://sass-lang.com/documentation/modules/string) with a dictionary general.

```scss
// String
@debug translator.translate(wrapper, general); // owijka
@debug translator.translate(technology, general); // tech

```

### Translate `list`

Translates [`list`](https://sass-lang.com/documentation/modules/list) with a dictionary general.

```scss
// List
@debug translator.translate(prefix (border, outline) color); // spectre (border, outline) color

```

### Translate `map`

```scss
// Map
@debug translator.translate((word: prefix (border, outline) color)); // (word: spectre (border, outline) color)
@debug translator.translate((word: wrapper), general); // (word: owijka)

```

### Nested key

Translates [`string`](https://sass-lang.com/documentation/modules/string) with a nested dictionary.

```scss
// Nested dictionary calendars
@debug translator.translate(calendar, (class, calendars)); // cal

```