Document 01-b · June 2026
mes-adresses (frontend) and mes-adresses-api (backend).
The engagement covers: wiring the i18n framework, extracting all French strings into
translation files, and manually testing the result.
No translation — strings stay in French, moved out of source code into the i18n catalog.
Adding a new language later means creating a new JSON file — no code changes.
The editor calls several French government APIs at runtime. Whether any of these services need to be forked will be decided in WS1.
| Service | Called by | Purpose | Required for local editing? |
|---|---|---|---|
geo.api.gouv.fr | frontend | Commune/INSEE search when creating a BAL | Yes |
plateforme-bal.adresse.data.gouv.fr/api-depot | frontend + backend | Submitting addresses to the national platform | No — publication only |
plateforme-bal.adresse.data.gouv.fr/moissonneur | frontend | Harvesting status from the national platform | No |
plateforme.adresse.data.gouv.fr (BAN) | backend | National address base API | No |
cadastre.data.gouv.fr | frontend | French land-registry (parcel) layer on the map | No — map works without it |
api.collectivite.fr | frontend + backend | French local authorities directory | No |
api-lannuaire.service-public.fr | frontend + backend | French public services directory | No |
api-signalement-prod.…scalingo.io | backend | Address-error reporting | No |
Map tiles (openmaptiles.geo.data.gouv.fr, data.geopf.fr) | frontend | Background map tiles, glyphs, sprites | Yes |
geo.api.gouv.fr (commune search when creating a BAL) and the map tile servers (for the map to render). All others are for national publication flows or optional features.No i18n framework is present today — all UI strings are hardcoded directly in source code. Stack: Evergreen UI · Next 16 · React 19.
Four passes over all .tsx and .ts source files — JSX text nodes, UI string props, toast content, and general string literals — combined and deduplicated.
| Pass | Unique strings |
|---|---|
| JSX text nodes | 127 |
| UI string props (label, placeholder, title…) | 202 |
| Toast / notification content | 14 |
| General string literals (.tsx) | 764 |
| General string literals (.ts — lib, contexts, hooks) | 301 |
| Combined & deduplicated | ~1 124 |
Per-area breakdown:
| Area | Unique strings | Notes |
|---|---|---|
| components/map | 188 | Layer names, style labels, controls |
| lib | 173 | API errors, enum values, status text |
| contexts | 150 | App-wide state messages |
| components/bal | 140 | Core editor UI |
| components/signalement | 104 | Confirm scope in WS1 |
| components/help | 66 | Long-form help prose |
| app/ (pages) | 61 | Legal / accessibility pages |
| components/new | 60 | BAL creation flow |
| components/habilitation-process | 50 | Publication flow — confirm scope in WS1 |
| components/settings + voie + toponyme + bal-recovery | ~132 | Core editor |
mes-adresses-api)Audited separately: ~24 strings, most already in technical English. A small number in French (habilitation/validation layer).
Recommendation: keep API errors as technical English. The frontend maps them to its own messages — all extraction lives in one place. The French API strings get converted to English as part of the extraction work. No extra volume added to the count above.
Of the ~50 repos in the org, only two are running locally today. WS1 locks the fork shortlist.
Method: curation matrix (repo → role → relevance → decision: keep / fork / stub / ignore) → review with Peter → confirm with Thierry.
Deliverable: curation matrix + fork shortlist with rationale.
Choose a library, wire it into the app, and extract all ~1 124 French strings into translation files. Strings stay in French.
| Library | Fit | Strength |
|---|---|---|
| next-intl ✦ recommended | Excellent — built for Next App Router | Simple API, RSC-ready, ICU plurals |
| lingui | Good | Best extraction tooling |
| i18next | Good | Largest ecosystem |
Also covers: key/namespace strategy, pluralization, date/number formatting, RTL readiness, wrapping Evergreen UI components.
Deliverable: i18n library wired, all ~1 124 strings in messages/fr.json, app running correctly in French with no hardcoded strings in source code.
Adding a new language later:
| File | Contents |
|---|---|
| messages/fr.json | Created here — French strings |
| messages/pt.json | Added later — same keys, Portuguese values |
| messages/en.json | Added later — same keys, English values |
Effort: 24–40 h.
Verify the app works correctly after the extraction.
What to check:
Deliverable: manual test script + seeded FR dataset (sample commune + BAL) for reproducible demos.
Effort: 4–8 h.
| Workstream | Effort |
|---|---|
| WS1 Repo curation | Gated on Peter / Thierry |
| WS2 i18n framework + full extraction | 24–40 h |
| WS3 Manual testing + seed dataset | 4–8 h |
| Total | ~28–48 h |
mes-adresses and mes-adresses-api?next-intl. Final choice with Peter.messages/fr.json.Documento 01-b · Junho de 2026
mes-adresses (frontend) e mes-adresses-api (backend).
O trabalho cobre: integrar o framework de i18n,
extrair todas as strings francesas para arquivos de tradução e testar o resultado manualmente.
Sem tradução — as strings ficam em francês, apenas removidas do código-fonte para o catálogo i18n.
Adicionar um novo idioma depois é só criar um novo arquivo JSON — sem alterar o código.
O editor chama vários serviços do governo francês em tempo de execução. Se algum desses serviços precisará ser forkado será decidido no WS1.
| Serviço | Chamado por | Finalidade | Necessário para edição local? |
|---|---|---|---|
geo.api.gouv.fr | frontend | Busca de commune/INSEE ao criar uma BAL | Sim |
plateforme-bal.adresse.data.gouv.fr/api-depot | frontend + backend | Envio de endereços para a plataforma nacional | Não — apenas para publicação |
plateforme-bal.adresse.data.gouv.fr/moissonneur | frontend | Status de coleta da plataforma nacional | Não |
plateforme.adresse.data.gouv.fr (BAN) | backend | API da base nacional de endereços | Não |
cadastre.data.gouv.fr | frontend | Camada de parcelas do cadastro francês no mapa | Não — mapa funciona sem ela |
api.collectivite.fr | frontend + backend | Diretório de coletividades locais francesas | Não |
api-lannuaire.service-public.fr | frontend + backend | Diretório de serviços públicos franceses | Não |
api-signalement-prod.…scalingo.io | backend | Reporte de erros de endereço | Não |
Tiles do mapa (openmaptiles.geo.data.gouv.fr, data.geopf.fr) | frontend | Tiles, glifos e sprites do mapa base | Sim |
geo.api.gouv.fr (busca de commune ao criar uma BAL) e os servidores de tiles do mapa (para o mapa renderizar). Os demais são para fluxos de publicação nacional ou funcionalidades opcionais.Nenhum framework de i18n existe hoje — todas as strings da UI estão escritas diretamente no código-fonte. Stack: Evergreen UI · Next 16 · React 19.
Quatro passes sobre todos os arquivos .tsx e .ts — nós de texto JSX, props de UI, conteúdo de toasts e literais de string gerais — combinados e deduplicados.
| Passe | Strings únicas |
|---|---|
| Nós de texto JSX | 127 |
| Props de UI (label, placeholder, title…) | 202 |
| Conteúdo de toasts / notificações | 14 |
| Literais de string gerais (.tsx) | 764 |
| Literais de string gerais (.ts — lib, contexts, hooks) | 301 |
| Combinado e deduplicado | ~1 124 |
Distribuição por área:
| Área | Strings únicas | Observações |
|---|---|---|
| components/map | 188 | Nomes de camadas, controles do mapa |
| lib | 173 | Erros de API, valores de enum, textos de status |
| contexts | 150 | Mensagens de estado globais |
| components/bal | 140 | Editor principal |
| components/signalement | 104 | Confirmar escopo no WS1 |
| components/help | 66 | Textos de ajuda longos |
| app/ (páginas) | 61 | Páginas legais / acessibilidade |
| components/new | 60 | Fluxo de criação de BAL |
| components/habilitation-process | 50 | Fluxo de publicação — confirmar escopo no WS1 |
| settings + voie + toponyme + bal-recovery | ~132 | Editor principal |
mes-adresses-api)Auditada separadamente: ~24 strings, a maioria já em inglês técnico. Um pequeno número em francês (camada de habilitação/validação).
Recomendação: manter os erros da API em inglês técnico. O frontend os mapeia para suas próprias mensagens — toda a extração fica em um único lugar. As strings francesas da API são convertidas para inglês como parte do trabalho. Sem volume extra na contagem acima.
Dos ~50 repositórios da organização, apenas dois estão rodando localmente hoje. O WS1 define a lista final de forks.
Método: matriz de curadoria (repo → papel → relevância → decisão: manter / forkar / simular / ignorar) → revisar com Peter → confirmar com Thierry.
Entregável: matriz de curadoria + lista de forks com justificativa.
Escolher uma biblioteca, integrá-la ao app e extrair todas as ~1 124 strings francesas para arquivos de tradução. As strings ficam em francês.
| Biblioteca | Adequação | Ponto forte |
|---|---|---|
| next-intl ✦ recomendada | Excelente — feita para o Next App Router | API simples, RSC-ready, plurais ICU |
| lingui | Boa | Melhor tooling de extração |
| i18next | Boa | Maior ecossistema |
Também cobre: estratégia de chaves/namespaces, pluralização, formatação de datas e números, suporte a RTL, integração com componentes do Evergreen UI.
Entregável: framework integrado, todas as ~1 124 strings em messages/fr.json, app rodando corretamente em francês sem strings hardcoded no código-fonte.
Adicionar um novo idioma depois:
| Arquivo | Conteúdo |
|---|---|
| messages/fr.json | Criado aqui — strings em francês |
| messages/pt.json | Adicionado depois — mesmas chaves, valores em português |
| messages/en.json | Adicionado depois — mesmas chaves, valores em inglês |
Esforço: 24–40 h.
Verificar que o app funciona corretamente após a extração.
O que verificar:
Entregável: script de teste manual + dataset FR de amostra (commune + BAL) para demos reproduzíveis.
Esforço: 4–8 h.
| Frente | Esforço |
|---|---|
| WS1 Curadoria de repositórios | Depende de Peter / Thierry |
| WS2 Framework i18n + extração completa | 24–40 h |
| WS3 Teste manual + dataset de amostra | 4–8 h |
| Total | ~28–48 h |
mes-adresses e mes-adresses-api?next-intl. Escolha final com Peter.messages/fr.json.