feat(i18n): francais comme langue principale, anglais accessible
Le site s'affiche desormais en francais par defaut, avec un selecteur de langue permettant de basculer vers l'anglais. Choix de conception : les chaines sources restent en anglais Elles servent d'identifiants gettext, et le francais est fourni par catalogue avec BABEL_DEFAULT_LOCALE = 'fr'. Le code reste ainsi dans une seule langue -- la meme que ses commentaires et docstrings -- tandis que ce qu'un membre voit est du francais. Consequence qui rend la migration praticable : une chaine non encore traduite retombe en anglais, pas sur un identifiant brut. Les gabarits peuvent donc etre migres un par un sans jamais laisser le site a moitie casse. Selection de la langue (app/i18n.py) 1. choix explicite via le selecteur, garde en session 2. sinon en-tete Accept-Language du navigateur, restreint a fr et en 3. sinon francais Un choix explicite prime toujours, y compris sur un navigateur anglophone. Selecteur Extrait en partiel et inclus dans les deux branches de la mise en page : barre laterale une fois connecte, ET page d'authentification. Quelqu'un qui ne lit pas la langue courante doit pouvoir en changer AVANT de se connecter -- le laisser derriere l'authentification aurait ete un defaut d'accessibilite. Chaque langue est ecrite dans sa propre langue. La route /lang/<locale> valide le Referer avant de rediriger : sans ce controle, elle constituait une redirection ouverte. Migre dans cette passe navigation complete, page de connexion, les cinq pages d'erreur, et l'integralite des messages flash de routes/auth.py. 64 chaines, dont aucune non traduite. Verification 25 tests, dont deux garde-fous d'integrite : un catalogue .mo manquant ou une entree non traduite font echouer la suite. Sans cela, une compilation oubliee servirait de l'anglais partout, en silence et sans rien dans les journaux. Un test existant a du etre corrige, et c'est instructif test_login_failure_message_does_not_reveal_account_existence cherchait la sous-chaine anglaise 'attempt(s) remaining'. La page etant desormais en francais, elle etait absente des deux cotes, l'assertion passait, et le mode strict a signale le faux succes. Le test comparait donc l'anglais, pas le comportement. Il compare desormais les messages flash rendus, quelle que soit la langue. La faille SEC-AUTH-006 reste ouverte, et le test la documente toujours. Les catalogues .po ET .mo sont versionnes : le deploiement est un simple miroir de fichiers, sans etape de compilation. messages.pot, regenerable, ne l'est pas. docs/translations.md documente le processus, les deux pieges (concatenation de phrases, traduction a l'import), et l'etat de la migration. A noter pour la suite : les chaines dans les blocs <script> ne peuvent pas etre balisees telles quelles, il faudra les passer par des attributs data- -- ce qui rejoint le chantier de sortie de unsafe-inline (OPS-010). Co-Authored-By: Claude Opus 5 <[email protected]>
This commit is contained in:
GGThed
@@ -0,0 +1,177 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user