# Texts and languages

The texts that a user sees belong to the modules that show them. A module does not know which other modules the app has, which languages they speak or how the app keeps its translations. So it gives its texts to the localization role, and reads them back through the role:

```mermaid
flowchart TB
    module["Module<br/>its texts, with translations"] -- "TextsData" --> role(["Localization role"])
    template["Template of another role<br/>its texts"] -- "TextsData" --> role
    role -- "the texts and the languages of the app" --> provider["Provider of the role<br/>a getter for each text"]
    provider -- "context.l10n" --> code["Code of the app"]
```

## A text and its owner

A text is a `LocalizedText`: a name, the text in English, and its translations by the code of their language, such as `uk`. The owner of a text is the module, or the template of a role, that gives it to the role as `TextsData`.

The role names every text apart from those of other owners. The getter of a text starts with the id of its owner in lowerCamelCase, followed by the name of the text: the text `title` of the module `haptics` is read as `context.l10n.hapticsTitle`. When the texts of two owners would still need one getter, the role reports them.

A text has no parameters and no plural forms, so neither its English text nor a translation has a brace.

## With the role and without it

A module that only uses the localization role works in an app without it too. Its templates read a text through a variable that the role makes for it, and the variable has one value for each kind of app:

| App | The variable `text_title` renders as |
| --- | --- |
| with the localization role | `context.l10n.hapticsTitle`, with the import of the file of the texts |
| without it | `'Haptic feedback'`, the English text as a literal |

The template of a role reads its texts the same way, through its render hook. [Texts](https://doc.saymyframe.com/extending/texts.md) shows the code.

## The languages of the app

The template of the role chooses the languages of the app before the app is rendered:

- By default, every language that a text of the app is in, English first and the others in the order the texts name them.
- With the option `--locales`, the languages that it names, in its order. English is always among them, since a text reads in English wherever it has no translation.

An app can be only in a language in which Flutter has the texts of its own widgets. The role knows those languages as `LocalizationRole.supportedLanguages`, the set of the oldest Flutter that SMF generates apps for. It leaves any other language of a text out of the app, and `--locales` refuses such a language. Without the option, the role warns of each language that it leaves out, with the owner and the texts. It always warns about each text that has no translation into a language of the app.

The role asks no question: the languages follow from the texts of the modules and from the option.

In an app that no route starts, [`flutter_core`](https://doc.saymyframe.com/modules/flutter-core.md#its-texts-and-the-languages-of-the-app), the module that every app has, gives the role the two texts of its fallback start screen, in English and in Ukrainian. The other built-in modules have their texts in both languages too. So by default an app with the role is in both languages, also an app without a feature.

## What the role generates

Whichever module provides the role, its template generates `lib/core/l10n/app_locale.dart` with:

- `appLocales`, the languages of the app as `Locale`s, the first of which the app uses when the device asks for none of them;
- `appLocale`, which keeps the language that the user chose: its `value` is one of `appLocales`, or `null` while the app follows the device, and `choose()` changes it;
- `AppLocaleScope`, the widget around the root of the app through which the root reads `appLocale`, so that it rebuilds in the new language when the choice changes;
- `restoreAppLocale()`, the restorer of the choice.

The template also gives the root `MaterialApp` its `locale`, its `supportedLocales` and the delegates of Flutter's own localizations, adds `flutter_localizations` to the app, and names the languages in the `Info.plist` of the iOS app. In the README of the app, it writes the section "Languages", which tells each place that a new language goes into.

## The language that the user chose

The language is a setting of the role, as [the theme mode](https://doc.saymyframe.com/concepts/settings.md#the-theme-mode-a-setting-of-a-role) is a setting of the theme role. So the role works with two more roles:

| Role | The localization role | What its template gives it |
| --- | --- | --- |
| Preferences | requires it | `restoreAppLocale`, a restorer. A choice is saved under the key `localization.locale`, as the code of the language, and removed when the app follows the device again. |
| Settings screen | uses it | In an app with a settings screen, `LanguageSetting`, the entry in which the user chooses a language of the app or the languages of the device, in `lib/core/l10n/language_setting.dart`. |

The texts of the entry are texts of the template itself, in English and in Ukrainian, which it gives the role only in an app with a settings screen. The entry shows a language by its name in that language. The role has the names of English and Ukrainian, and `smf create` warns of any other language of such an app, whose name the developer adds to the file of the entry.

Because the role requires the preferences, an app with a module that provides the localization always has a module that provides the preferences, and remembers the language. [Languages](https://doc.saymyframe.com/guides/languages.md#the-language-that-the-user-chose) shows `appLocale` from the side of the app.

## What the provider generates

The provider keeps the texts. It generates `lib/core/l10n/l10n.dart` with the extension `AppTexts` on `BuildContext`, whose getter `l10n` returns an object with a `String` getter for each text of the app:

- Each getter returns the text in the language of the context, or in English when the text has no translation into that language.
- The provider renders the texts in the languages of the app only.
- `context.l10n` works in every context below the root of the app, in the language that the root is in, also once that language changes.

How the texts get there is the provider's choice: in files of translations that a tool turns into code, or in Dart code. [`gen_l10n`](https://doc.saymyframe.com/modules/gen-l10n.md) keeps them in ARB files, one for each language, from which gen-l10n of Flutter generates the code. A provider that loads its texts with a delegate adds the delegate to the `localizationsDelegates` of the root.

## Rules

In an app with the role, the role checks the modules before the app is generated, and the contract harness checks the generated code:

| Rule | What it requires |
| --- | --- |
| `localization.texts` | The texts of a module have lowerCamelCase names that differ, an English text, translations by the code of their language, and no braces. A variable of a brick that reads a text reads one that the app has, and is its English text in an app without the role. A text in the data of another role, such as the label of a destination, is among the texts that its module gave the role, and two such texts of one name do not differ. |
| `localization.text_access` | Code of a module reads only its own texts and those of the modules it depends on. The template of a role reads its own, and the texts in the data that the modules give its role or a role that it requires or uses, such as the labels of the destinations. |
| `localization.texts_rendered` | A file of the provider names the getter of every text of the app. |

The role also says what holds at the root of the app. Every delegate among the `localizationsDelegates` of the root supports each language of the app, and the `supportedLocales` of the root are those of the role alone: the argument takes the items of one contributor, so `smf create` reports a module that gives the root a locale of its own as a conflict with the role. So a module brings no delegate for texts of its own, which would have to know the languages of the app, and adds no language to the root. It gives its texts to the role.

## Next

- [Languages](https://doc.saymyframe.com/guides/languages.md) shows what the app has and how its code reads a text.
- [Texts](https://doc.saymyframe.com/extending/texts.md) shows how a module gives its texts and reads them in its templates.
- [Provide the localization](https://doc.saymyframe.com/extending/provide-localization.md) covers a provider of the role.
