Bite 31 — Brazilian Portuguese Demo Readiness - RodrigoMattosoSilveira/EnterpriseRemoteSystems GitHub Wiki

Introduction

I would revise the roadmap.

Given that Brazilian prospects are your immediate commercial audience, I think Brazilian Portuguese demo readiness should become Bite 31, and Production Data Protection should move to Bite 32.

That is not abandoning the backup risk. It is recognizing that ERS now has a different near-term value constraint: you need to be able to sell and demonstrate what you have built.

There is also good backlog support for this choice. Issue #304 — Implement I18N infrastructure — is still open, is already labeled p-1 / Next in line, and explicitly says to break the work into small, testable bites.

I would define Bite 31 as

Bite 31 — Brazilian Portuguese Demo Readiness

The goal should not be:

Translate every string in ERS before doing anything else.

That could become a large diversion.

The goal should instead be:

A Brazilian prospect can experience a coherent, professionally presented ERS demonstration in Brazilian Portuguese, from sign-in through the principal business workflows, without encountering obvious English-only gaps or improvised demo data.

That combines three things that belong together commercially:

  1. real i18n infrastructure rather than hardcoded Portuguese;
  2. pt-BR coverage of the demo-critical application paths;
  3. repeatable presentation/demo material so you can demonstrate ERS consistently.

Proposed sub-bites

31.1 — I18N Foundation and Locale Contract

Establish the architectural foundation first:

  • en-US and pt-BR;
  • locale selection/fallback;
  • translation resources organized by domain;
  • no component-level if Portuguese... hacks;
  • correct Brazilian date, time, number and currency formatting;
  • tests for missing keys and fallback behavior;
  • decide whether locale is browser-derived, user-selectable, or both.

English should remain the fallback language.

This should absorb the infrastructure intent of #304 rather than inventing another parallel mechanism.

31.2 — Common Shell, Authentication, and Administration Translation

Translate the surfaces a prospect sees immediately:

  • sign-in;
  • application shell/navigation;
  • Administration context;
  • Tenant selector;
  • common buttons/actions;
  • confirmation/error/empty/loading states;
  • authentication/account terminology;
  • Tenant administration where it appears in the demo.

This matters disproportionately because a single untranslated navigation label makes an otherwise Portuguese demo feel unfinished.

31.3 — Core Business Demo Journey in pt-BR

Then translate a deliberately selected customer story rather than the entire application.

I would make the first Brazilian demo journey something like:

Sign in
  ↓
Select Tenant
  ↓
People
  ↓
Collaborators / Collaborator Journey
  ↓
Planning / Work Plan
  ↓
Expenses
  ↓
Balances / Ledger
  ↓
Receipts / Settlement

That naturally lines up with much of the existing i18n backlog around People, Planning, Expenses and Receipts.

The acceptance rule should be strong:

Once the Brazilian-language demo starts, the presenter should not have to explain away untranslated English UI in the demonstrated workflow.

We can translate less frequently demonstrated administration/support pages later.

31.4 — Brazilian Demo Dataset and Repeatable Scenario

This is important enough to make explicit.

We should create a controlled demo scenario with:

  • Brazilian names;
  • BRL values;
  • realistic CPF/phone/address-style presentation where appropriate, using clearly fictional/non-real data;
  • Collaborator/Journey history;
  • Work Plan;
  • Expense examples;
  • receipts;
  • balances;
  • a few intentionally useful states such as pending vs completed.

The data should support a story, not merely populate tables.

I would avoid using real Production customer/person data in sales demonstrations.

31.5 — Demo Presentation and Presenter Scripts

This is where the commercial value becomes usable.

I would prepare at least:

  • a short Brazilian-Portuguese ERS overview deck;
  • a live-demo script in Brazilian Portuguese;
  • an English presenter version if useful to you;
  • a shorter “executive demo” sequence;
  • a deeper operational demo sequence;
  • recovery instructions if the demo gets off script;
  • talking points explaining Tenant isolation, Person/Collaborator/Journey distinctions, expenses, settlement, receipts and auditability.

The script should tell you what to click, what to say, and what business value the screen demonstrates.

That is much better than simply translating the interface and then improvising the presentation.

What I would not put into Bite 31

I would deliberately exclude:

  • translating every administration/developer-only screen;
  • backend/database internationalization that has no visible demo impact;
  • multilingual user-generated content;
  • automatic machine translation;
  • more than en-US + pt-BR;
  • SaaS licensing;
  • PostgreSQL;
  • device authorization;
  • broad unrelated UX cleanup.

Those can follow.

The risk here is classic scope expansion: “make the demo Portuguese” becomes “internationalize the entire product.” We should prevent that.

Acceptance criteria I would use

At Bite 31 completion:

  • ERS supports pt-BR through a real i18n layer.
  • English remains functional and is the fallback.
  • The demo-critical workflow can be completed entirely in Brazilian Portuguese.
  • Dates/numbers/currency display appropriately for pt-BR.
  • No significant hardcoded English text appears in that workflow.
  • Changing locale does not alter business data or authorization state.
  • Existing English E2E tests continue to pass.
  • New tests verify translation-key completeness for the Bite 31 scope.
  • A repeatable Brazilian demo dataset exists.
  • A presenter can reset/reproduce the demo state.
  • A Brazilian-Portuguese presentation and live-demo script exist.
  • The full scripted demonstration has been manually rehearsed from beginning to end.

And because this is ERS, I would make the manual tests very UI-heavy. Translation defects are exactly the sort of thing automated tests will miss: clipped text, awkward vocabulary, inconsistent capitalization, English remnants, bad BRL formatting, labels that technically translate but make no business sense.

Then Bite 32 should be the hardening work

I would revise the near-term roadmap to:

Bite 31
Brazilian Portuguese Demo Readiness
    31.1 I18N foundation
    31.2 Common/Auth/Admin pt-BR
    31.3 Core business demo journey pt-BR
    31.4 Repeatable Brazilian demo dataset
    31.5 Presentation + demo scripts

        ↓

Bite 32
Production Data Protection and Recovery Hardening
    scheduled backups
    retention
    restore verification
    off-server replication
    recovery rehearsal

        ↓

Bite 33
Business-Rule Integrity Audit / #11

        ↓

Bite 34
PostgreSQL / scalability foundation

There is one condition I would attach to that recommendation: Bite 31 must stay commercially focused and bounded. I would not allow “complete internationalization of ERS” to postpone #840 indefinitely. Issue #840 still represents a real Production survivability gap.

So I would make the sequencing decision explicit in the Bite 31 parent issue:

Bite 31 is intentionally prioritized ahead of Production Data Protection because Brazilian Portuguese demo readiness is an immediate customer-acquisition requirement. Bite 31 is limited to the infrastructure and application surfaces required for a professional Brazilian prospect demonstration. Production Data Protection and Recovery Hardening is the mandatory next major Bite after Bite 31.

That gives you both commercial urgency now and operational discipline immediately afterward.

I think this is a better roadmap for where ERS is today. You have spent a long sequence making the architecture trustworthy. The next thing the product needs is not another invisible architectural improvement—it needs to become convincing to the people you want to buy it.