team-tryouts/docs/translations.md

# Translations

French is the primary language of the site. English remains available
through the switcher in the sidebar (and on the login page, for visitors
who have not signed in yet).

---

## 1. How it works

Source strings stay **in English** and act as gettext message ids. The
French wording lives in a catalogue.

```
app/i18n.py                                    locale selection
app/translations/fr/LC_MESSAGES/messages.po    French catalogue (edited)
app/translations/fr/LC_MESSAGES/messages.mo    compiled (read at runtime)
app/translations/en/LC_MESSAGES/messages.po    English, msgstr == msgid
babel.cfg                                      extraction rules
```

This keeps the codebase in one language — the same one as its comments and
docstrings — while what a member sees defaults to French.

**A string with no translation falls back to English**, not to a raw
identifier. That is why this migration can proceed template by template
without ever leaving the site half broken: an untranslated page is a page
in English, not a page full of `nav.dashboard.label`.

### Which language a visitor gets

1. An explicit choice made through the switcher, kept in the session.
2. Failing that, the browser's `Accept-Language`, restricted to `fr` and `en`.
3. Failing that, French.

An explicit choice always wins, including over an English browser.

---

## 2. Marking a string for translation

### In a template

```jinja
<span>{{ _('Dashboard') }}</span>
<p>{{ _('The page you are looking for does not exist.') }}</p>
```

With a value inside:

```jinja
{{ _('Welcome back, %(username)s!', username=user.username) }}
```

For a longer block:

```jinja
{% trans %}This tryout has ended and can no longer be modified.{% endtrans %}
```

### In Python

```python
from flask_babel import gettext as _

flash(_('This account has been deactivated.'), 'danger')
flash(_('Welcome back, %(username)s!', username=user.username), 'success')
```

### Two things that do not work

**Never build a sentence by concatenation.** Word order differs between
languages, and the translator sees fragments with no context.

```python
flash(_('Player ') + name + _(' has been removed.'))   # no
flash(_('%(name)s has been removed.', name=name))      # yes
```

**Never translate at import time.** A module-level `_()` runs before any
request exists, so it resolves once, in whatever locale happened to be
active — usually the default. Use `lazy_gettext` when the string has to sit
in a constant or a class attribute:

```python
from flask_babel import lazy_gettext as _l

ROLE_LABELS = {'coach': _l('Coach'), 'player': _l('Player')}
```

Extraction picks up `_l` because `babel.cfg` is invoked with `-k _l`.

---

## 3. Updating the catalogues

After marking new strings:

```bash
# 1. Re-extract every marked string
pybabel extract -F babel.cfg -k _l -o messages.pot --project=team-tryouts .

# 2. Merge into the existing catalogues, keeping current translations
pybabel update -i messages.pot -d app/translations

# 3. Fill in the new French entries
#    edit app/translations/fr/LC_MESSAGES/messages.po

# 4. Compile
pybabel compile -d app/translations
```

`messages.pot` is regenerable and not tracked. The `.po` and `.mo` files
**are** tracked: deployment is a plain file mirror with no build step, so
an uncompiled catalogue would mean an English-only site in production.

### Entries needing attention

`pybabel update` marks changed strings as `#, fuzzy`. A fuzzy entry is
**ignored at runtime** — the string falls back to English. Review the
guessed translation, then remove the `#, fuzzy` line.

### Adding a language

```bash
pybabel init -i messages.pot -d app/translations -l es
```

Then add the code to `SUPPORTED_LOCALES` and `LOCALE_NAMES` in
`app/i18n.py`. The switcher picks it up on its own.

---

## 4. Checks

`tests/test_i18n.py` fails the build when:

- a compiled `.mo` is missing — otherwise the site silently serves English
  everywhere, with nothing in the logs;
- a catalogue still contains an untranslated entry.

That second check is what keeps the migration honest: adding
`{{ _('...') }}` to a template without translating it turns the suite red.

---

## 5. State of the migration

Done: navigation, login page, the five error pages, and every flash message
in `app/routes/auth.py`.

Remaining, roughly in order of how often a member sees them:

| Area | Files |
|---|---|
| Dashboard | `pages/dashboard.html` |
| Tryouts | `pages/tryouts.html`, `view_tryout.html`, `tryout_form.html` |
| Registration | `pages/register.html` |
| Profile | `pages/profile.html`, `edit_profile.html` |
| Teams | `pages/teams.html`, `my_teams.html` |
| Calendar and matches | `pages/calendar.html`, `match_form.html`, `team_matches.html` |
| Notes and One on One | `pages/notes.html`, `one_on_one.html`, `add_note.html`, … |
| Contracts | `pages/contracts.html`, `upload_contract.html` |
| Remaining flash messages | `routes/users.py`, `tryouts.py`, `teams.py`, `matches.py`, … |

Two things to keep in mind while continuing.

**Strings inside `<script>` blocks** cannot be marked with `{{ _() }}` and
left at that — see `SEC-XSS-001`. Pass translated text through a `data-`
attribute, or a `<script type="application/json">` block read by an
external file. This lines up with the work needed to drop `unsafe-inline`
from the CSP (`OPS-010`), so the two are best done together, template by
template.

**Validation messages in `app/validators.py`** are shown to users and are
not yet marked. They need `lazy_gettext`, since schema fields are built at
import time.