# Phrasebooks

## Translations

Flow Connect supports building multilingual applications, components, and portal pages. Translations are managed in **Phrasebooks** — dictionaries of named *phrases* that you reference from the user interface and scripts instead of typing the text directly.

Two kinds of Phrasebook work together:

* A **local Phrasebook** is built into a single Application or Component. Its phrases are only available inside that container, and are referenced through the implicit `Phrase` module.
* A **Phrasebook asset** is a shared, reusable Phrasebook. It can be enabled as a dependency by any Application, Component, or Portal Page that needs the same translations, and its phrases are referenced through the **asset's name** — the same way Modules are referenced.

{% hint style="warning" %}
Translations cannot be used in machine steps running on the connector agent.
{% endhint %}

### ICU Message Format

Phrase values use the **ICU Message Format**, an international standard for writing messages that adapt to different languages, grammar rules, and contexts. ICU supports plural forms, grammatical gender, and date/time formatting in a single string. For example, this message produces a grammatically correct sentence in English regardless of the count:

```
{count, plural,
  =0 {You have no messages.}
  one {You have one message.}
  other {You have # messages.}
}
```

### Opening the Phrasebook

The Phrasebook is opened from the **Phrasebook icon** in the toolbar at the bottom of the Designer canvas.

<div data-with-frame="true"><figure><img src="/files/jOZvbxoxvNVs80ynaVX5" alt=""><figcaption></figcaption></figure></div>

The Phrasebook window has two responsibilities:

* Managing the **local Phrasebook** — the phrases owned by the current Application or Component.
* Enabling references to **Phrasebook assets** so their phrases can be used in this Application or Component.

<div data-with-frame="true"><figure><img src="/files/ncPMsNT1bZlE2EF1oyjX" alt=""><figcaption></figcaption></figure></div>

### The Phrasebook table

A Phrasebook is a table where each row defines one phrase. Each phrase has:

* A unique **ID** that follows variable naming rules. The ID is used to reference the phrase from the UI and scripts.
* A **Default language** value, written in your primary development language.
* Any number of **translated values**, one per additional language added with the **+ Language** button.

The default value is also the fallback when the client's language has no translation. If your organization mostly operates in English, write defaults in English and add other languages as additional columns — there is no need for a separate English column.

You can **Import** and **Export** the Phrasebook from the same window — useful for sending phrases to a translator or bulk-loading translations.

**Example**

| Unique ID | Default language | Swedish (sv) |
| --------- | ---------------- | ------------ |
| greeting  | Hello            | Hej          |
| open      | Open             | Öppna        |
| close     | Close            | Stäng        |

#### Local Phrasebook

Every Application and Component has its own local Phrasebook. The phrases listed directly in the Phrasebook table are the local phrases.

Local phrases are always available through the implicit `Phrase` module. To make a **Header** control display the `greeting` phrase, write `{Phrase.greeting}` in its **Text** field.

Use the local Phrasebook for translations that only apply inside one Application or Component.

#### Phrasebook assets

A **Phrasebook asset** is a Phrasebook stored as a shared, reusable asset, so the same translations can be used by many Applications, Components, and Portal Pages. Phrasebook assets are managed in the same way as Components and Modules — they are committed, versioned, and enabled as dependencies.

**Creating a Phrasebook asset**

To create a new Phrasebook asset, go into the Application Library or one of your Application Packages and click the ➕ symbol in the **Assets** panel.

* A Phrasebook asset placed directly in the **Application Library** can be enabled by any Application, Component, or Portal Page in the organization.
* A Phrasebook asset placed inside an **Application Package** can only be enabled from within that Package.

Editing a Phrasebook asset works the same as editing a local Phrasebook: rows for phrases, a default language value, and one column per translated language.

**Enabling a Phrasebook asset**

A Phrasebook asset must be enabled before its phrases become available in an Application, Component, or Portal Page.

In the Phrasebook window, click **Add Phrasebook**. The dropdown lists all Phrasebook assets visible to the current Application, Component, or Portal Page, grouped by their source — the **Application Library** or the specific **Application Package** they live in. Each asset shows the committed version that will be referenced (for example, *v4*).

Use the toggle next to a Phrasebook asset to enable or disable it.

<div data-with-frame="true"><figure><img src="/files/FWYxQdN9bpONDJbiqzsB" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
Only **committed** Phrasebook assets can be enabled. Assets that have only an uncommitted Head version appear in the list but the toggle is disabled until the asset has been committed.
{% endhint %}

Once enabled, the asset is exposed as a module named after the asset itself — the same way a referenced **Module** is exposed. To use the `greeting` phrase from a Phrasebook asset called `CommonLabels`, write `{CommonLabels.greeting}` in any Template-enabled field.

{% hint style="info" %}
Local phrases and asset phrases live in **separate namespaces**. Local phrases are reached through `Phrase`, asset phrases through the asset's own name. An Application or Component can enable any number of Phrasebook assets in addition to its own local Phrasebook.
{% endhint %}

**Versioning**

When you enable a Phrasebook asset, the **latest committed version** is used. As you commit new versions of the asset, Applications, Components, and Portal Pages that reference it update automatically the next time they are edited and saved. This is the same model used by Components and Modules, including transitive references.

{% hint style="info" %}
It is useful to work "bottom-up" with Phrasebook assets: develop and commit the asset first, then enable it from Applications, Components, and Portal Pages.
{% endhint %}

**When to use a Phrasebook asset**

Reach for a Phrasebook asset when:

* The same phrases are needed across multiple Applications or Components — for example, common UI labels like *Save*, *Cancel*, or *Confirm*.
* A Package contains several Applications and Components that should share consistent terminology.
* A central group is responsible for translations and you want them to maintain a single source of truth instead of duplicating phrases.

### Using phrases

Phrases are referenced through whichever module they belong to:

* Phrases in the local Phrasebook are accessed through the implicit `Phrase` module: `{Phrase.greeting}`.
* Phrases in a Phrasebook asset are accessed through the **asset's name**: `{CommonLabels.greeting}`.

Translations can be used almost anywhere in Flow Connect, including step controls, components, and client-side scripts.

#### Two ways to use an existing phrase

There are two ways to insert an existing phrase into a Template-enabled field:

* **Type the reference** directly — for example `{Phrase.greeting}` or `{CommonLabels.greeting}`. Designer's autocomplete will help find phrases as you type.
* **Browse phrases** — click the three-dot menu to the right of the field, or press **Ctrl + .** (Windows) or **⌘.** (macOS) to bring up the *Editor menu*, then select **Browse phrases**. A picker lets you search across the local Phrasebook and any enabled Phrasebook assets, and inserts the correct reference for you.

The same Editor menu also has an **Open Phrasebooks** shortcut, which jumps straight to the Phrasebook window from any control without leaving the field.

<div data-with-frame="true"><figure><img src="/files/NJmatJ6vd8zOOyAI2iYL" alt=""><figcaption></figcaption></figure></div>

### Adding phrases inline

While building the user interface, you can add new phrases on the fly without leaving the Designer:

* Type a value into a Template-enabled configuration field — the **Text** of a **Header** control, for example.
* Click the three-dot menu to the right of the field, or press **Ctrl + .** (Windows) or **⌘.** (macOS) to bring up the *Editor menu*.
* Select **Add to Phrasebook**.
* Review the suggested unique ID and, optionally, add translations.
* Press **OK**.

The original value is replaced with a reference to the new phrase in the local Phrasebook.

### Parameterized phrases

A phrase can declare ICU Message Format **arguments** so that values are substituted at runtime:

| Unique ID | Default language | French (fr)      |
| --------- | ---------------- | ---------------- |
| greeting  | Hello {name}!    | Bonjour, {name}! |

A phrase with at least one argument is exposed as a *function* on its module. To call the local `greeting` phrase, write `{Phrase.greeting('Thomas')}`. To call the same phrase from a Phrasebook asset called `CommonLabels`, write `{CommonLabels.greeting('Thomas')}`. Either renders as "Hello Thomas!" in English and "Bonjour, Thomas!" in French.

A phrase with more than one argument is invoked with a **Record** containing the arguments. The ICU string `Hello {firstName} {lastName}` is called as `{Phrase.greeting({firstName: 'Alicia', lastName: 'Sanchez'})}` (or `{CommonLabels.greeting({firstName: 'Alicia', lastName: 'Sanchez'})}` if the phrase lives in an asset).

### Pluralization and more

Because phrases use ICU Message Format, you can express plural forms, grammatical gender, and date/time formatting in a single string. The following phrase takes one argument, `messageCount`, and produces a grammatically correct sentence in English ("You have one message" vs. "You have 5 messages"):

```
{messageCount, plural,
  =0 {You have no messages.}
  one {You have one message.}
  other {You have # messages.}
}
```

### Application metadata

Application packages and applications also have **name** and **description** metadata that is translated separately, in the Hub — not in the Designer Phrasebook. See [Translate applications](/flow-connect/reference/how-to-guides/translate-applications.md) for that workflow.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.novacura.com/flow-connect/working-with-connect/create-and-design/phrasebooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.