# Texts

A text that a user sees belongs to the module that shows it. The module gives its texts to the localization role, in English and in the other languages that it has them in, and its templates read them through the role. A module that only uses the role works in an app without it too, where each text reads in English. [Texts and languages](https://doc.saymyframe.com/concepts/localization.md) explains the role.

The examples come from the module `haptics` of [Add a setting](https://doc.saymyframe.com/extending/settings.md), whose row on the settings screen has a label.

## Declare the texts

```dart
static const _texts = TextsData([
  LocalizedText(
    'title',
    en: 'Haptic feedback',
    translations: {'uk': 'Вібровідгук'},
  ),
]);
```

| Part | Rules |
| --- | --- |
| The name | A lowerCamelCase identifier, such as `title` or `openDetails`, with a name of its own among the texts of the module. Names that differ only in case count as one. |
| `en` | The text in English, which is never empty. The app shows it in every language that the text has no translation into, and in an app without the role. |
| `translations` | The text in other languages, by the code of each: two or three lowercase letters without a region, such as `uk`. English is not among them, and no translation is empty. Leave a language out to show the text in English there. |

A text takes no parameters and has no plural forms, so no text has a `{` or a `}`.

An app can be only in a language in which Flutter has the texts of its own widgets, one of `LocalizationRole.supportedLanguages`. A translation into any other language is left out of the app. Unless `--locales` chose the languages, `smf create` warns of it, with the module and the text.

## Give the texts to the role, and read them

The module lists the role in `uses`, gives it the texts as data, and gives its brick a variable for each text:

```dart
uses: {preferencesRole, settingsScreenRole, localizationRole},
```

```dart
BrickContribution(
  hapticsSettingBundle,
  vars: localizationRole.varsOf(id, _texts),
  when: const {settingsScreenRole},
),
localizationRole.data(_texts, when: const {settingsScreenRole}),
```

The `when` of both contributions is about the row of `haptics`, as [the section below](#texts-that-only-some-apps-need) explains. A module whose texts every app needs leaves it out.

`varsOf` makes the variable `text_<name>` for each text, with the name in snake_case: `title` is `text_title`, and `openDetails` is `text_open_details`. A template reads it where a widget shows the text:

```dart
title: Text({{{text_title}}}),
```

The variable renders by the app:

| App | `Text({{{text_title}}})` renders as |
| --- | --- |
| with the localization role | `Text(context.l10n.hapticsTitle)`, and the file gets the import of `lib/core/l10n/l10n.dart` |
| without it | `Text('Haptic feedback')` |

The getter of a text starts with the id of the module in lowerCamelCase, followed by the name of the text with a capital: `title` of `haptics` is `hapticsTitle`, and `ok` of `firebase_core` would be `firebaseCoreOk`.

A template reads a text variable by these rules:

- in three braces, and outside every mustache section;
- where a `BuildContext context` below the root `MaterialApp` is in scope, such as in the `build` of a widget;
- not inside a `const` expression, since `context.l10n.hapticsTitle` is not a constant. A widget that is `const` only in an app without the role gets the keyword from an inverted section next to the variable, as in `{{^has_localization}}const {{/has_localization}}Text({{{text_title}}})`.

Give the role the same texts as `varsOf` gets. In an app with the role, `smf create` reports a variable whose text no module gave the role, since the module that provides the role would have no getter for it.

## Texts that only some apps need

The label of `haptics` is needed only in an app with a settings screen, where its row is. So the brick that reads it and the data of the texts both name that role in `when`, as the contributions above do. The settings screen role asks for the first: a module that only uses it generates the file of its row only in an app with a settings screen. The second keeps a text that no screen shows out of the app.

A text variable cannot be read inside `{{#has_<role>}}`. A text that needs another role goes into a brick of its own, contributed with `when` of that role, as here. See [variables that depend on a role](https://doc.saymyframe.com/extending/templates.md#variables-that-depend-on-a-role).

## Whose texts code may read

The code of a module reads only its own texts and those of the modules in its `dependsOn`, each through its getter. In an app with the role, the contract harness checks it for every text that code reads from `context.l10n` or from a variable called `l10n`.

A module brings no delegate for texts of its own and adds no language to the root of the app. Every delegate of the root has to support each language of the app, and only the role knows them.

## Texts in the data of another role

The data that a module gives another role can have a text that a user sees too. The label of a destination is one: a feature gives it to the router role in its routes, as `Destination(label: ...)`, and the layout role shows it. Such a text is a `LocalizedText` of the module like any other:

- A module that lists the localization role gives that role the same text among its `TextsData`. The app then reads the text from its texts, in its language. In an app with the role, `smf create` reports a text of such data that the module did not give the role, or gave it otherwise.
- A module that does not list the role gives the text in English alone, which every app shows. `smf create` reports a translation there, which no app would show.
- Two such texts of one name that differ are an error, since the app reads a text of a module by its name and would show the same text for both.

[Write a feature module](https://doc.saymyframe.com/extending/feature-module.md#the-route-and-the-tab) has the label of a tab as the example. A role whose data has such texts implements `DataWithTexts` in the data, and its template reads each text with `expressionOf`, as the next section shows.

## Texts of the template of a role

The template of a role gives its texts the same way, when its role lists the localization role in `uses` or `requires`. A render hook takes no variable of `varsOf`, so the template reads each text with `expressionOf`. The theme role does this for the texts of its row on the settings screen:

```dart
@override
RoleOutput render(RoleHookInput<NoDsl> input) => RoleOutput(
      vars: {
        'mode_key': SmfNames.dartString(ThemeRole.modeKey),
        for (final MapEntry(key: variable, value: text) in _texts.entries)
          variable: localizationRole.expressionOf(
            input,
            const RoleTemplateOrigin(themeRole),
            text,
          ),
      },
    );
```

The getter of such a text starts with the id of the role: the text `title` of the theme role is `context.l10n.themeTitle`. The template reads its own texts, and the texts in the data that the modules give its role, each as a text of the module that gave it.

## In tests

The contract harness checks the rules of the texts in the apps with the localization role. So the registry of the tests of a module with texts has a module that provides the role, such as `GenL10nModule` of `smf_gen_l10n`, and one that provides the preferences, which the role requires. The harness then builds the apps of the module with the role and without it.

A test of a module reads what the module gave the role from the role, not from the files of the module that provides it:

```dart
final input = localizationRole.hookInput(result.hook!);
final texts = localizationRole.textsIn(input);
final languages = localizationRole.localesIn(input);
```

`textsIn` returns the texts of the whole app, each with its owner. An app of the tests that no route starts has the texts of `flutter_core` too, the two of its fallback start screen in English and in Ukrainian, so its languages include Ukrainian whatever the module under test gives. A test takes the texts of its own module by their owner:

```dart
final own = [
  for (final text in texts)
    if (text.owner == const ModuleOrigin(HapticsModule.id)) text.getter,
];
```

See [Test a module](https://doc.saymyframe.com/extending/testing.md#checking-one-app).
