# translate.string()

The `translate.string()` function returns a translated [`$string`](#usdstring) with a global dictionary(if in use) and/or [`$dictionary`](#usddictionary) if translation is found, otherwise not translated [`$string`](#usdstring).

{% hint style="info" %}
Global dictionary is in use on [`$dictionary-global`](https://docs.angular-package.dev/sass/dictionary/dictionary.variables#usddictionary-global-true) set to `true`, or by setting `$global` argument to `true`.
{% endhint %}

{% code lineNumbers="true" %}

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

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

// The `translator.translate-string()` or `translate.string()` function.
@function string($string, $key: null, $dictionary: (), $global: null) {
  @return if(
    type-of($string) == string,
    dictionary.translation(
        $string,
        translator.dictionary($key, $dictionary, $global)
      )
      or $string,
    $string
  );
}
```

{% endcode %}

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

### Parameters

#### `$string`

A `string` to translate with a global dictionary and/or [`$dictionary`](#usddictionary).

#### `$key: null`

A key to retrieve the dictionary from a global(if in use) and/or [`$dictionary`](#usddictionary).

#### `$dictionary: ()`

The dictionary that is used to translate [`$string`](#usdstring).

#### `$global: null`

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

### Return

The return value is translated [`$string`](#usdstring) retrieved from a global dictionary(if in use) and/or [`$dictionary`](#usddictionary).

## 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,
  border: b,
  class: (prefix: class-prefix, separator: class-separator, suffix: class-suffix, calendars: (calendar: cal), labels: (label: lab)),
  color: c,
  general: (word: słowo, (wrapper, wrap): owijka, (technology, technologia): tech, color: c),
  large: lg,
  medium: md,
  outline: o,
  prefix: spectre,
  small: sm,
  suffix: end,
));

// Default translate.
@debug translator.translate-string(prefix); // spectre

// Translate from the sub-dictionary `class`.
@debug translator.translate-string(prefix, class); // class-prefix

// Translate string with delimiter '-'.
@debug translator.translate-string(extra-large); // xl
@debug translator.translate-string(extra-large, class); // xl

// Translate with a provided `$dictionary`.
@debug translator.translate-string(prefix, class, $-dictionary-example); // class-prefix
@debug translator.translate-string(word, general, $-dictionary-example); // słowo
@debug translator.translate-string(wrap, general, $-dictionary-example); // owijka
@debug translator.translate-string(wrapper, general, $-dictionary-example); // owijka

// Nested key.
@debug translator.translate-string(calendar, (class, calendars), $-dictionary-example); // cal

// Deactivate global dictionary.
@debug translator.translate-string(extra-large, $global: false); // extra-large

```