Phase 1 — Analysis & Estimate

Document 01-b · June 2026

This document is the analysis. Scope: the editor repositories — 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.

External service dependencies

The editor calls several French government APIs at runtime. Whether any of these services need to be forked will be decided in WS1.

ServiceCalled byPurposeRequired for local editing?
geo.api.gouv.frfrontendCommune/INSEE search when creating a BALYes
plateforme-bal.adresse.data.gouv.fr/api-depotfrontend + backendSubmitting addresses to the national platformNo — publication only
plateforme-bal.adresse.data.gouv.fr/moissonneurfrontendHarvesting status from the national platformNo
plateforme.adresse.data.gouv.fr (BAN)backendNational address base APINo
cadastre.data.gouv.frfrontendFrench land-registry (parcel) layer on the mapNo — map works without it
api.collectivite.frfrontend + backendFrench local authorities directoryNo
api-lannuaire.service-public.frfrontend + backendFrench public services directoryNo
api-signalement-prod.…scalingo.iobackendAddress-error reportingNo
Map tiles (openmaptiles.geo.data.gouv.fr, data.geopf.fr)frontendBackground map tiles, glyphs, spritesYes
For local editing, only two matter in practice: 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.

These are all French-government services. Making them pluggable for other countries is the core of the internationalization work, but is out of scope for this phase.

String count

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.

PassUnique strings
JSX text nodes127
UI string props (label, placeholder, title…)202
Toast / notification content14
General string literals (.tsx)764
General string literals (.ts — lib, contexts, hooks)301
Combined & deduplicated~1 124

Per-area breakdown:

AreaUnique stringsNotes
components/map188Layer names, style labels, controls
lib173API errors, enum values, status text
contexts150App-wide state messages
components/bal140Core editor UI
components/signalement104Confirm scope in WS1
components/help66Long-form help prose
app/ (pages)61Legal / accessibility pages
components/new60BAL creation flow
components/habilitation-process50Publication flow — confirm scope in WS1
components/settings + voie + toponyme + bal-recovery~132Core editor
~1 124 unique strings to extract. Regex-based figure — not 100% exact but sufficient to estimate the work.

API strings (backend — 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.

Workstreams

WS1 — Repo curation Gated on Peter & Thierry

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.

WS2 — i18n framework + full string extraction

Choose a library, wire it into the app, and extract all ~1 124 French strings into translation files. Strings stay in French.

LibraryFitStrength
next-intl ✦ recommendedExcellent — built for Next App RouterSimple API, RSC-ready, ICU plurals
linguiGoodBest extraction tooling
i18nextGoodLargest 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:

FileContents
messages/fr.jsonCreated here — French strings
messages/pt.jsonAdded later — same keys, Portuguese values
messages/en.jsonAdded later — same keys, English values

Effort: 24–40 h.

WS3 — Manual testing & demo

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.

Estimate summary

WorkstreamEffort
WS1 Repo curationGated on Peter / Thierry
WS2 i18n framework + full extraction24–40 h
WS3 Manual testing + seed dataset4–8 h
Total~28–48 h

Open decisions

Done when…

Fase 1 — Análise & Estimativa

Documento 01-b · Junho de 2026

Este documento é a análise. Escopo: os repositórios do editor — 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.

Dependências de serviços externos

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çoChamado porFinalidadeNecessário para edição local?
geo.api.gouv.frfrontendBusca de commune/INSEE ao criar uma BALSim
plateforme-bal.adresse.data.gouv.fr/api-depotfrontend + backendEnvio de endereços para a plataforma nacionalNão — apenas para publicação
plateforme-bal.adresse.data.gouv.fr/moissonneurfrontendStatus de coleta da plataforma nacionalNão
plateforme.adresse.data.gouv.fr (BAN)backendAPI da base nacional de endereçosNão
cadastre.data.gouv.frfrontendCamada de parcelas do cadastro francês no mapaNão — mapa funciona sem ela
api.collectivite.frfrontend + backendDiretório de coletividades locais francesasNão
api-lannuaire.service-public.frfrontend + backendDiretório de serviços públicos francesesNão
api-signalement-prod.…scalingo.iobackendReporte de erros de endereçoNão
Tiles do mapa (openmaptiles.geo.data.gouv.fr, data.geopf.fr)frontendTiles, glifos e sprites do mapa baseSim
Para edição local, apenas dois são necessários na prática: 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.

Todos são serviços do governo francês. Torná-los plugáveis para outros países é o núcleo do trabalho de internacionalização, mas está fora do escopo desta fase.

Contagem de strings

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.

PasseStrings únicas
Nós de texto JSX127
Props de UI (label, placeholder, title…)202
Conteúdo de toasts / notificações14
Literais de string gerais (.tsx)764
Literais de string gerais (.ts — lib, contexts, hooks)301
Combinado e deduplicado~1 124

Distribuição por área:

ÁreaStrings únicasObservações
components/map188Nomes de camadas, controles do mapa
lib173Erros de API, valores de enum, textos de status
contexts150Mensagens de estado globais
components/bal140Editor principal
components/signalement104Confirmar escopo no WS1
components/help66Textos de ajuda longos
app/ (páginas)61Páginas legais / acessibilidade
components/new60Fluxo de criação de BAL
components/habilitation-process50Fluxo de publicação — confirmar escopo no WS1
settings + voie + toponyme + bal-recovery~132Editor principal
~1 124 strings únicas a extrair. Número obtido via regex — não é 100% exato, mas suficiente para estimar o trabalho.

Strings da API (backend — 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.

Frentes de trabalho

WS1 — Curadoria dos repositórios Depende de Peter & Thierry

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.

WS2 — Framework i18n + extração completa

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.

BibliotecaAdequaçãoPonto forte
next-intl ✦ recomendadaExcelente — feita para o Next App RouterAPI simples, RSC-ready, plurais ICU
linguiBoaMelhor tooling de extração
i18nextBoaMaior 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:

ArquivoConteúdo
messages/fr.jsonCriado aqui — strings em francês
messages/pt.jsonAdicionado depois — mesmas chaves, valores em português
messages/en.jsonAdicionado depois — mesmas chaves, valores em inglês

Esforço: 24–40 h.

WS3 — Teste manual e demo

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.

Resumo da estimativa

FrenteEsforço
WS1 Curadoria de repositóriosDepende de Peter / Thierry
WS2 Framework i18n + extração completa24–40 h
WS3 Teste manual + dataset de amostra4–8 h
Total~28–48 h

Decisões em aberto

Concluído quando…